Developer CD Series 1996 April: Mac OS SDK/Dev.CD Apr 96 SDK/Dev.CD Apr 96 SDK1.toast/Development Kits (Disc 1)/OpenDoc/Sample Code/Sample Editors⁄Viewers/Picture Viewer/Source/PictureViewer.cpp

Text File | 1995-12-08 | 138.9 KB | 4,367 lines | [TEXT/MPS ]

/*------------------------------------------------------------------------------
    File:            PictureViewer.cpp

    Written by:        Sue Dumont        [based on SamplePart by Steve Smith]

    Copyright:        © 1994-95 by Apple Computer, Inc., all rights reserved.

    Description:    PictureViewer demonstrates the functionality of a
                    viewer part.

    Demonstrates:     1. Open
                     2. Adding A Display Frame
                     3. Adding A Facet
                     4. Part Drawing
                     5. Refcounting Geometry
                     6. ViewTypes & Presentations
                     7. Display Frame 'ternalization
                     8. Part Init & Externalization
                     9. Part Init & partWrapper
                    10. Part Storage Model
                    11. Persistent Reference
                    12. RefCounting
                    13. Storage Unit
                    14. Activation
                    15. Basic Event Handling
                    16. Menu Handling
                    17. Windows & Dialogs
                    18. Exception Handling
                    19. Memory Manager
                    20. Using Resources
                    21. Lazy Frame Internalization
                    22. Writing/Fulfilling Promises

    Notes:        •    somThis is not set in methods where our internal data
                    members are not accessed.

                •    A viewer's stationery doesn't have any functionality.

                •    Temp objects are automatically released when they go
                    out of scope, so there's no need to release them.
------------------------------------------------------------------------------*/

// -- Compiler/Preprocessor Notification --

#ifndef _COMPILERDEFS_
#include "CompDefs.h"
#endif

// -- OpenDoc Utilities --

#ifndef _EXCEPT_
// Exceptions define several important macros (eg. CHECKENV)
// which are used in the SOM method dispatch glue. If Except.h
// is not included early enough, exceptions may not be thrown
// correctly when returning from a SOM method with the "ev" parameter set.
#include <Except.h>
#endif

// -- PictureViewer Includes

// Notification that this is a SOM source file
#define SampleCode_PictureViewer_Class_Source

// define underscore (_) field names
#define VARIABLE_MACROS

#ifndef _PICTUREVIEWERDEF_
#include "PictureViewerDef.h"
#endif

#ifndef _PICTUREVIEWERGLOBALS_
#include "PictureViewerGlobals.h"
#endif

#ifndef _PICTUREVIEWERUTILS_
#include "PictureViewerUtils.h"
#endif

#ifndef SOM_SampleCode_PictureViewer_xih
#include "PictureViewer.xih"
#endif

#ifndef _SAMPLECOLLECTIONS_
#include "SampleCollections.h"
#endif

// -- OpenDoc Includes --

#ifndef SOM_ODArbitrator_xh
#include <Arbitrat.xh>
#endif

#ifndef SOM_ODCanvas_xh
#include <Canvas.xh>
#endif

#ifndef SOM_ODClipboard_xh
#include <Clipbd.xh>
#endif

#ifndef SOM_Module_OpenDoc_Commands_defined
#include <CmdDefs.xh>
#endif

#ifndef SOM_ODDraft_xh
#include <Draft.xh>
#endif

#ifndef SOM_ODFacet_xh
#include <Facet.xh>
#endif

#ifndef SOM_ODFrameFacetIterator_xh
#include <FrFaItr.xh>
#endif

#ifndef SOM_Module_OpenDoc_Foci_defined
#include <Foci.xh>
#endif

#ifndef SOM_ODFocusSet_xh
#include <FocusSet.xh>
#endif

#ifndef SOM_ODMenuBar_xh
#include <MenuBar.xh>
#endif

#ifndef SOM_ODSession_xh
#include <ODSessn.xh>
#endif

#ifndef SOM_ODShape_xh
#include <Shape.xh>
#endif

#ifndef SOM_Module_OpenDoc_StdDefs_defined
#include <StdDefs.xh>
#endif

#ifndef SOM_Module_OpenDoc_StdProps_defined
#include <StdProps.xh>
#endif

#ifndef SOM_Module_OpenDoc_StdTypes_defined
#include <StdTypes.xh>
#endif

#ifndef SOM_ODStorageUnit_xh
#include <StorageU.xh>
#endif

#ifndef SOM_ODTranslation_xh
#include <Translt.xh>
#endif

#ifndef SOM_ODWindow_xh
#include <Window.xh>
#endif

#ifndef SOM_ODWindowState_xh
#include <WinStat.xh>
#endif


// -- OpenDoc Utilities --

#ifndef _FOCUSLIB_
#include <FocusLib.h>
#endif

#ifndef _ISOSTR_
#include <ISOStr.h>
#endif

#ifndef _ITEXT_
#include <IText.h>
#endif

#ifndef _ODDEBUG_
#include <ODDebug.h>
#endif

#ifndef _ODMEMORY_
#include <ODMemory.h>
#endif

#ifndef _ODNEW_
#include <ODNew.h>
#endif

#ifndef _ODUTILS_
#include <ODUtils.h>
#endif

#ifndef _STDTYPIO_
#include <StdTypIO.h>
#endif

#ifndef _STORUTIL_
#include <StorUtil.h>
#endif

#ifndef _TEMPOBJ_
#include <TempObj.h>
#endif

#ifndef _TEMPITER_
#include <TempIter.h>
#endif

#ifndef _USERSRCM_
#include <UseRsrcM.h>
#endif

// -- Macintosh Includes --

#ifndef __DIALOGS__
#include <Dialogs.h>
#endif

#ifndef __ERRORS__
#include <Errors.h>
#endif

#ifndef __GXMATH__
#include <GXMath.h>
#endif

#ifndef __ICONS__
#include <Icons.h>                // NewIconSuite, PlotIconSuite, DisposeIconSuite
#endif

#ifndef __QUICKDRAW__
#include <Quickdraw.h>
#endif

#ifndef __PICTUTILS__
#include <PictUtils.h>
#endif

#ifndef __RESOURCES__
#include <Resources.h>
#endif

#ifndef __TEXTUTILS__
#include <TextUtils.h>
#endif

#ifndef __TOOLUTILS__
#include <ToolUtils.h>
#endif


#pragma segment PictureViewer


//==============================================================================
// PictureViewer
//==============================================================================

//------------------------------------------------------------------------------
// Method:        somInit
// Origin:        SOMObject
//
// Description:    somInit and somUninit methods behave like C++ constructors
//                in that the inherited methods are called automatically.
//                There is no need to call the parent class' somInit or somUninit.
//
//                Also, instance variables need not be initialized to 0 or kODNULL
//                since SOM guarantees that a newly constructed object is zeroed.
// Warnings:    You are not allowed to throw an exception from this method.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__somInit
            (
                SampleCode_PictureViewer*    somSelf
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","somInit");

    _fDisplayMode        = kCommandCrop;        // default display
    _fReadOnlyStorage    = kODFalse;
}

//------------------------------------------------------------------------------
// Method:        somUninit
// Origin:        SOMObject
//
// Description:    This is the SOM equivalent of a C++ clas destructor. In this
//                routine you should clean up any class members which weren't
//                taken care of in the ReleaseAll and Release methods.
//
// Warning:        You are not allowed to throw an exception from this method.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__somUninit
            (
                SampleCode_PictureViewer*    somSelf
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","somUninit");
}

//------------------------------------------------------------------------------
// Method:        Release
// Origin:        ODRefCountedObject
//
// Description:    This method is called each time an object releases the
//                part. If the refcount falls to 0, the part should
//                release the _fSelf part reference.
//
// Warning:        If the part releases any other object when the refcount falls
//                to zero, it will need to override the Acquire method so that
//                the object can be referenced again if the parts refcount should
//                be incremented before it is deleted.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__Release
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","Release");

    SOM_TRY
        SampleCode_PictureViewer_parent_ODPart_Release(somSelf, ev);

        if ( _fSelf->GetRefCount(ev) == 0 )
            ODGetDraft(ev, _fSelf)->ReleasePart(ev, _fSelf);
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        ReleaseAll
// Origin:        ODPersistentObject
//
// Description:    This method is called just prior to the part being
//                deleted by the Draft. The part must release all
//                references to all refcounted objects it has stored
//                internally; not doing so, will cause an "invalid ref
//                count" exception/error.
//
//                If any promises exist on the clipboard, it is the part's
//                responsibility to fulfill them at this time.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__ReleaseAll
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","ReleaseAll");

    SOM_TRY
        // If the last part instance using the globals is released,
        // we need to clean up and delete the globals.

        if ( --gGlobalsUsageCount == 0 )
        {
            // Release the menubar.
            ODReleaseObject(ev, gGlobals->fMenuBar);

            // Delete the objects stored in the globals struct.
            ODDeleteObject(gGlobals->fUIFocusSet);
            ODDisposePtr(gGlobals->fPictScrapKind);
            ODDisposePtr(gGlobals->fPictFileKind);
            ODDisposePtr(gGlobals->fAppleHFSFlavor);

            // Delete the globals struct.
            ODDeleteObject(gGlobals);
        }

        // Dispose of the picture handle.
        if ( _fPicture )
            ODDisposeHandle(_fPicture);

        if ( _fGWorld )
        {
            DisposeGWorld((GWorldPtr)_fGWorld);
            _fGWorld = kODNULL;
        }

        if ( _fDisplayFrames )
        {
            CListIterator fiter(_fDisplayFrames);
            for ( CFrameProxy* proxy = (CFrameProxy*)fiter.First();
                    fiter.IsNotComplete(); proxy = (CFrameProxy*)fiter.Next() )
            {
                // Delete the proxy object and its contents. The frame's
                // refcount will be decremented in the proxy destructor.
                fiter.RemoveCurrent();
                delete proxy;
            }

            // Delete the display frame collection.
            ODDeleteObject(_fDisplayFrames);
        }

        SampleCode_PictureViewer_parent_ODPart_ReleaseAll(somSelf, ev);

    SOM_CATCH_ALL
        // If something goes wrong while we are cleaning up, we must
        // let the Draft know because there may be some refcounted objects
        // which did not get released. Not to mention, possible memory
        // leaks.
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        Purge
// Origin:        ODObject
//
// Description:    This method is called when the draft runs out of
//                memory or when a part is being deleted. The part
//                should free up as much memory as possible.
//
//                The part determines which views are being used in
//                its display frames. The resources for the unused view
//                types are purged.
//
// Note:         The calculations in this routine determine the
//                amount of memory a specific icon requires at a
//                specified bit depth.
//------------------------------------------------------------------------------
SOM_Scope    ODSize
SOMLINK        PictureViewer__Purge
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODSize                        size
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","Purge");

    // Purge is called during the creation of stationery. However,
    // we have not create our internal display frames list, so
    // trying to iterate over it would be futile.
    if ( _fDisplayFrames == kODNULL )
        return 0;

    ODSize         bytesFreed        = 0;
    ODBoolean    usingThumbnail  = kODFalse;

    SOM_TRY
        // Iterate over the frames we are displayed through and determine
        // which view types are currently in use.

        CListIterator fiter(_fDisplayFrames);
        for ( CFrameProxy* proxy = (CFrameProxy*) fiter.First();
                fiter.IsNotComplete(); proxy = (CFrameProxy*) fiter.Next() )
        {
            // If the display frame is real (was connected or added),
            // get its view type; otherwise, ignore it.
            if ( proxy->FrameIsLoaded(ev) )
            {
                ODTypeToken    frameView = proxy->GetFrame(ev)->GetViewType(ev);

                if ( frameView == gGlobals->fThumbnailView )
                    usingThumbnail = kODTrue;

                    // Release the frame reference, but don't get rid of the
                    // proxy object because we're not done with the frame. If
                    // all parts release their references the frame will be
                    // purged from memory.
                    proxy->Purge(ev);
            }
        }

        // Based on the usage of the supported view types, free up as much
        // memory as possible.

        if ( !usingThumbnail && _fGWorld != kODNULL )
        {
            bytesFreed += (ODSize)sizeof(CGrafPort);
            PixMapHandle pixMap = GetGWorldPixMap((GWorldPtr)_fGWorld);
            bytesFreed += (ODSize)ODGetHandleSize((Handle)pixMap);

            DisposeGWorld((GWorldPtr)_fGWorld);
            _fGWorld = kODNULL;
        }
    SOM_CATCH_ALL
    SOM_ENDTRY

    return bytesFreed;
}

//------------------------------------------------------------------------------
// Method:        InitPart
// Origin:        ODPart
//
// Description:    This method is called ONLY when new stationery is being
//                created for the part. This method should write out all
//                standard/default properties and values that the part
//                expects to see.
//
// Warning:        It is not appropriate to require user interaction while
//                stationery is being created. Do not present the user
//                with error dialogs or splash screens.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__InitPart
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODStorageUnit*                    storageUnit,
                ODPart*                            partWrapper
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","InitPart");

    SOM_TRY
        // We must call the initialize method of our parent
        // class to allow OpenDoc to annotate our part's storageUnit, to
        // set our refcount, and to change our "initialized" flag to true.
        SampleCode_PictureViewer_parent_ODPart_InitPart(somSelf, ev, storageUnit,
                                                        partWrapper);

          // To allow editor swapping (translation) at runtime, OpenDoc requires
        // that we pass in a "reference" to ourselves when interacting with the
        // API (eg. WindowState::RegisterWindow(), Dispatcher::RegisterIdle, etc).
        // The "partWrapper" passed to us here and in InitPartFromStorage is the
        // "reference" OpenDoc is asking us to use.
        _fSelf = partWrapper;

        // We are being created, either as part of generating stationery or
        // by some editor instantiating the part, so the destination storage
        // unit must be writeable.
        _fReadOnlyStorage = kODFalse;

        // Call the common initialization code to get set up.
        somSelf->Initialize(ev);

        // Since we have just been created, our state/content info has
        // never been written out, so setting our "dirty" flag will
        // give us a chance to do that.
        somSelf->SetDirty(ev);
    SOM_CATCH_ALL
        // Clean up will occur in the destructor which will be called
        // shortly after we return the error.
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        InitPartFromStorage
// Origin:        ODPart
//
// Description:    This method is called when a document/stationery is
//                being opened or when the part is internalized by its
//                containing part. The part should merely read in its
//                saved state/content and initialize itself. The part
//                 must not alter its storage unit; otherwise, the "Save"
//                 menu item becomes enabled without the user actually
//                having made a change to the document.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__InitPartFromStorage
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODStorageUnit*                storageUnit,
                ODPart*                        partWrapper
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","InitPartFromStorage");

    SOM_TRY
        // Call the initialize method of our parent PersistentObject class to generate
        // the appropriate time/date stamp on our part's storage unit.
        SampleCode_PictureViewer_parent_ODPart_InitPartFromStorage(somSelf,
                                                ev, storageUnit, partWrapper);

        // To allow editor swapping (translation) at runtime, OpenDoc requires
        // that we pass in a reference to ourselves when interacting with the
        // API (eg. WindowState::RegisterWindow(), Dispatcher::RegisterIdle, etc).
        // The "partWrapper" passed to us here and in InitPart is the
        // "reference" OpenDoc is asking us to use.
        _fSelf = partWrapper;

        // Are we being opened from a read-only draft? If so, we cannot
        // write anything back out to our storage unit.
        _fReadOnlyStorage = ( ODGetDraft(ev, storageUnit)->
                                GetPermissions(ev) < kODDPSharedWrite );

        // Call the common initialization code to get set up.
        somSelf->Initialize(ev);

        // Read in the state the part was in when it was last Externalized.
        // This allows the part to present the same environment the user
        // had the part set up in the last time it was displayed.
        somSelf->InternalizeStateInfo(ev, storageUnit);

        // Read in the contents for the part editor/viewer.
        somSelf->InternalizeContent(ev, storageUnit, kODNULL);

    SOM_CATCH_ALL
        // Clean up will occur in the destructor which will be called
        // shortly after we return the error.
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        Initialize
// Origin:        PictureViewer
//
// Description:    This method is called during the internalization of the part
//                from a document. Its purpose is to initialize all fields of
//                the part and to convert ISO types to tokens for faster
//                comparisons throughout the code.
//
//                If an exception is thrown in this method, it wil be propogated
//                back to OpenDoc which will call our ReleaseAll() method and the
//                class destructor. All memory allocated here will be cleaned up
//                in the ReleaseAll() method.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__Initialize
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","Initialize");

    SOM_TRY
        ODStorageUnit* storageUnit = _fSelf->GetStorageUnit(ev);

        // Store a reference to the Session object.
        _fSession = storageUnit->GetSession(ev);

        // Create a list to keep track of the frames we are being
        // displayed in. Used for maintenance (ie., Purging memory).
        _fDisplayFrames = new CList;

        // Check to see if we need to initialize our globals.
        if ( gGlobalsUsageCount == 0 )
        {
            // Create our globals space. We store the globals in a struct so
            // that we can put them in temp mem. Otherwise, CFM loads the globals
            // with the data fragment of a CFM library in the application heap.
            gGlobals = new PictureViewerGlobals;

            somSelf->InitializeMenuBar(ev);

            // We tokenize the values here and store them for equivalence
            // tests in the activation methods.
            gGlobals->fSelectionFocus = _fSession->Tokenize(ev, kODSelectionFocus);
            gGlobals->fClipboardFocus = _fSession->Tokenize(ev, kODClipboardFocus);
            gGlobals->fMenuFocus = _fSession->Tokenize(ev, kODMenuFocus);
            gGlobals->fModalFocus = _fSession->Tokenize(ev, kODModalFocus);

            // Tokenize our part's main presentation, the default presentation
            // and the standard view types.
            gGlobals->fMainPresentation    = _fSession->Tokenize(ev, kMainPresentation);

            gGlobals->fFrameView = _fSession->Tokenize(ev, kODViewAsFrame);
            gGlobals->fLargeIconView = _fSession->Tokenize(ev, kODViewAsLargeIcon);
            gGlobals->fSmallIconView = _fSession->Tokenize(ev, kODViewAsSmallIcon);
            gGlobals->fThumbnailView = _fSession->Tokenize(ev, kODViewAsThumbnail);

            // This part supports PICT data files, so we must get the value type
            // from OpenDoc. We do this through the Translation object.
            gGlobals->fPictScrapKind = _fSession->GetTranslation(ev)->
                            GetISOTypeFromPlatformType(ev, kPictureDataType, kODPlatformDataType);

            gGlobals->fPictFileKind = _fSession->GetTranslation(ev)->
                            GetISOTypeFromPlatformType(ev, kPictureDataType, kODPlatformFileType);

            gGlobals->fAppleHFSFlavor = _fSession->GetTranslation(ev)->
                            GetISOTypeFromPlatformType(ev, flavorTypeHFS, kODPlatformDataType);

            // We will also package the menu and selection foci so
            // that we can request the "set" at activation time.
            gGlobals->fUIFocusSet = _fSession->GetArbitrator(ev)->CreateFocusSet(ev);
            gGlobals->fUIFocusSet->Add(ev, gGlobals->fMenuFocus);
            gGlobals->fUIFocusSet->Add(ev, gGlobals->fSelectionFocus);

            // Determine what Script/Language the part is localized for.
            // This is important/necessary for creating OpenDoc's text objects.
            GetEditorScriptLanguage(ev, &gGlobals->fEditorScript,
                                                &gGlobals->fEditorLanguage);

            // The first client of the global variables is running.
            gGlobalsUsageCount = 1;
        }
        else
        {
            // If the globals have been initialized, we just bump the "usage"
            // count so that we know how many part instances are using them.
            gGlobalsUsageCount++;
        }
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        InitializeMenuBar
// Origin:        PictureViewer
//
// Description:    This method is called during the initialization process and
//                when the menubar object becomes invalid.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__InitializeMenuBar
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","InitializeMenuBar");

    SOM_TRY
        // Clean up the menubar object if it already exists.
        if ( gGlobals->fMenuBar )
            ODReleaseObject(ev, gGlobals->fMenuBar);

        // It is required that parts instantiate their menubars from the base
        // OpenDoc menu bar. This maintains consistency in the default menu
        // items and their placement. Since the object is a copy, we can add
        // and subtract menus and items without affecting other running parts.
        gGlobals->fMenuBar = _fSession->GetWindowState(ev)->CopyBaseMenuBar(ev);

        CUsingLibraryResources res;

        // Add Display menu for Crop and Scale commands.
        gGlobals->fMenuBar->AddMenuLast(ev, kDisplayMenuID,
                                        GetMenu(kDisplayMenuID), _fSelf);

        // Register the Display menu commands. Crop is the first menuitem,
        // and Scale is the second menuitem.
        gGlobals->fMenuBar->RegisterCommand(ev, kCommandCrop, kDisplayMenuID, 1);
        gGlobals->fMenuBar->RegisterCommand(ev, kCommandScale, kDisplayMenuID, 2);
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        InternalizeStateInfo
// Origin:        PictureViewer
//
// Description:    This method reads in state information. This is information
//                related to the workings of the part editor, not the content.
//
//                The part writes out a list of weak references to its display
//                frames. This allows the part to reuse the same display frames
//                each time the document is opened. Those references are read
//                back in and validated here.
//
// Note:        The StorageUnit interface requires the use of the ODByteArray
//                struct. Look in StorUtil.h/cpp for an example of using the
//                ODByteArray struct.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__InternalizeStateInfo
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODStorageUnit*                storageUnit
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","InternalizeStateInfo");

    TRY
        ODStorageUnitRef    weakRef;
        ODULong                size;

        // Internalize the part's display frame list.
        if ( storageUnit->Exists(ev, kODPropDisplayFrames, kODWeakStorageUnitRefs, 0) )
        {
            storageUnit->Focus(ev, kODPropDisplayFrames, kODPosUndefined,
                                        kODWeakStorageUnitRefs, 0, kODPosUndefined);

            size = storageUnit->GetSize(ev);
            storageUnit->SetOffset(ev, 0);

            for (ODULong offset = 0; offset < size; offset += kODStorageUnitRefSize)
            {
                TRY
                    StorageUnitGetValue(storageUnit, ev, kODStorageUnitRefSize,
                                            (ODPtr)&weakRef);

                    if ( storageUnit->IsValidStorageUnitRef(ev, weakRef) )
                    {
                        // We lazily internalize our display frames, meaning we don't get
                        // the frame until we absolutely need it. This reduces the time
                        // to internalize the part and the amount of memory needed.

                        // Convert the reference into a runtime id.
                        ODID frameID = storageUnit->GetIDFromStorageUnitRef(ev, weakRef);

                        // Create a proxy class to support the lazy internalization.
                        CFrameProxy* proxy = new CFrameProxy;
                        proxy->InitFrameProxy(frameID, ODGetDraft(ev, storageUnit));

                        // Add the proxy to the display frame collection.
                        _fDisplayFrames->Add(proxy);
                    }
                CATCH_ALL
                    // consume exception
                ENDTRY
            }
        }

        // Internalize the display mode setting
        if ( storageUnit->Exists(ev, kPropDisplayMode, kODSLong, 0) )
            _fDisplayMode = ODGetSLongProp(ev, storageUnit, kPropDisplayMode, kODSLong);
    CATCH_ALL
        // consume the exception, so don't set the ev parameter
    ENDTRY
}

//------------------------------------------------------------------------------
// Method:        InternalizeContent
// Origin:        PictureViewer
//
// Description:    This method is called during interalization of the
//                part. The content of the part should be read in.
//
//                The part should look for content properties in the order of
//                highest to lowest fidelity. This ensures the most accurate
//                reproduction of the internalized content.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__InternalizeContent
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODStorageUnit*                    storageUnit,
                ODFacet*                        facet
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","InternalizeContent");

    ODULong        size;

    SOM_TRY
        if ( storageUnit->Exists(ev, kODPropContents, gGlobals->fPictScrapKind, 0) )
        {
            // Check for the Macintosh PICT scrap type.
            storageUnit->Focus(ev, kODPropContents,
                                kODPosUndefined,
                                gGlobals->fPictScrapKind,
                                0,
                                kODPosUndefined);

            size = storageUnit->GetSize(ev);

            TRY
                if ( size > 0 )
                {
                    // Allocate memory for the new picture data. If we are
                    // successful, dispose of any old data and assign
                    // the new storage to our part.
                    ODHandle tempPict = ODNewHandle(size);

                    TempODHandleLock hLock(tempPict);
                    StorageUnitGetValue(storageUnit, ev, size, *hLock);

                    if ( _fPicture )
                        ODDisposeHandle(_fPicture);
                    _fPicture = tempPict;
                }
            CATCH_ALL
            ENDTRY
        }
        else if ( ODSUExistsThenFocus(ev, storageUnit, kODPropContents, gGlobals->fAppleHFSFlavor) )
        {
            size = storageUnit->GetSize(ev);

            if ( size > 0 )
            {
                HFSFlavor* hfsInfo = (HFSFlavor*) ODNewPtrClear(size);

                // Assign the pointer to a temp mem pointer so that the memory block
                // will be automatically disposed of when it goes out of scope or in
                // case an exception occurs.
                // is thrown.
                TempODPtr autoDisposer = (ODPtr)hfsInfo;

                StorageUnitGetValue(storageUnit, ev, size, hfsInfo);

                if ( hfsInfo->fileType == kPictureDataType )
                {
                    // PICT data exists, so read it in.
                    somSelf->ReadPictureFile(ev, facet, hfsInfo, size);

                    TRY
                        // Write out our preferred kind.
                        ODSetISOStrProp(ev, storageUnit, kODPropPreferredKind,
                                                kODISOStr, gGlobals->fPictScrapKind);
                    CATCH_ALL
                        // Remove the property and value if something went wrong.
                        ODSURemoveProperty(ev, storageUnit, kODPropPreferredKind);
                    ENDTRY

                    // Call SetDirty so our content will be externalized.
                    somSelf->SetDirty(ev);
                }
            }
        }
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        Externalize
// Origin:        ODPersistentObject
//
// Description:    Write out the state information (display frames)
//                to persistent storage. Also, be sure to call the
//                parent class because one or more of its parent classes
//                may contain implementation.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__Externalize
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","Externalize");

    // Ask our parent classes to externalize themselves.
    SampleCode_PictureViewer_parent_ODPart_Externalize(somSelf, ev);

    SOM_TRY
        if ( _fDirty && !_fReadOnlyStorage )
        {
            // Get our storage unit.
            ODStorageUnit* storageUnit = _fSelf->GetStorageUnit(ev);

            // Verify that the storage unit has the appropriate properties
            // and values to allow us to run. If not, add them.
            somSelf->CheckAndAddProperties(ev, storageUnit);

            // Verify that there are no "bogus" values in the Content
            // property.
            somSelf->CleanseContentProperty(ev, storageUnit);

            // Write out the content data.
            somSelf->ExternalizeContent(ev, storageUnit, kODNULLKey, kODNULL);

            // Write out the part's state information.
            somSelf->ExternalizeStateInfo(ev, storageUnit, kODNULLKey, kODNULL);

            // Flag our part as no longer being dirty.
            _fDirty = kODFalse;
        }
    SOM_CATCH_ALL
        // Alert the user of the problem.
        somSelf->HandleDialogBox(ev, kODNULL, kErrorBoxID, kErrExternalizeFailed);
        // Change the error code value so the DocShell doesn't
        // display an error dialog.
        SetErrorCode(kODErrAlreadyNotified);
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        ExternalizeStateInfo
// Origin:        PictureViewer
//
// Description:    This method is called during externalization of the part.
//                The current state of the part should be written out. This
//                state information may be lost during Data Interchange
//                operations, so the part needs to recover gracefully if
//                information is missing or incomplete.
//
// Note:        The function StorageUnitSetValue is a macro which simplifies
//                the use of ODByteArrary, which is required by the StorageUnit
//                interface. Look in StorUtil.h/cpp for an example of using the
//                ODByteArray struct.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__ExternalizeStateInfo
             (
                 SampleCode_PictureViewer*        somSelf,
                 Environment*                    ev,
                 ODStorageUnit*                    storageUnit,
                 ODDraftKey                        key,
                 ODFrame*                        scopeFrame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","ExternalizeStateInfo");

    ODStorageUnitRef    weakRef;
    ODID                frameID;
    ODID                scopeFrameID;
    ODDraft*            fromDraft;

    SOM_TRY
        scopeFrameID = (scopeFrame ? scopeFrame->GetID(ev) : kODNULLID );
        fromDraft = ODGetDraft(ev, _fSelf);

        // Externalize the part's display frame list.
        storageUnit->Focus(ev, kODPropDisplayFrames, kODPosUndefined,
                                    kODWeakStorageUnitRefs, 0, kODPosUndefined);

        // Persistent object references are stored in a side table, rather than
        // in the property/value stream. Thus, deleting the contents of a value
        // will not delete the references previously written to that value. To
        // completely delete all references written to the value, we must
        // remove the value and add it back.
        storageUnit->Remove(ev);
        storageUnit->AddValue(ev, kODWeakStorageUnitRefs);

        CListIterator fiter(_fDisplayFrames);
        for ( CFrameProxy* proxy = (CFrameProxy*)fiter.First();
                fiter.IsNotComplete(); proxy = (CFrameProxy*)fiter.Next() )
        {
            TRY
                // Get the ID of the frame we are going to weakly reference.
                frameID = proxy->GetID();

                // If a draft key exists, then we are being cloned to another draft.
                // We must "weak" clone our display frame and reference the cloned
                // frame. The part re-uses the frameID variable so there aren't two
                // different GetWeakStorageUnitRef calls.
                if ( key )
                    frameID = fromDraft->WeakClone(ev, key, frameID, kODNULLID, scopeFrameID);

                // Write out weak references to each of the part's display frames.
                storageUnit->GetWeakStorageUnitRef(ev, frameID, weakRef);
                StorageUnitSetValue(storageUnit, ev, kODStorageUnitRefSize, (ODPtr)&weakRef);
            CATCH_ALL
                // consume the exception, so don't set ev parameter
            ENDTRY
        }

        // Externalize the display mode
        ODSetSLongProp(ev, storageUnit, kPropDisplayMode, kODSLong, _fDisplayMode);
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        ExternalizeContent
// Origin:        PictureViewer
//
// Description:    This method is called during exteralization of the
//                part. The content of the part should be written out.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__ExternalizeContent
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODStorageUnit*                 storageUnit,
                ODDraftKey                     key,
                ODFrame*                    scopeFrame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","ExternalizeContent");

    SOM_TRY
        // Focus to our content property.
        storageUnit->Focus(ev, kODPropContents, kODPosUndefined,
                            gGlobals->fPictScrapKind, 0, kODPosUndefined);

        ODULong oldSize = storageUnit->GetSize(ev);

        if ( _fPicture )
        {
            ODULong pictSize = ODGetHandleSize(_fPicture);

            // Write out the data. Use temp mem for the handle lock.
            TempODHandleLock hLock(_fPicture);
            StorageUnitSetValue(storageUnit, ev, pictSize, *hLock);

            // Delete the extra bytes in the value.
            if ( oldSize > pictSize )
                storageUnit->DeleteValue(ev, (oldSize - pictSize));
        }
        else
        {
            // If we don't have content data, but data exists in the
            // storage unit, delete it.
            if ( oldSize > 0 )
                storageUnit->DeleteValue(ev, oldSize);
        }
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        ExternalizeKinds
// Origin:        ODPart
//
// Description:    This method is called when the user wants to save the document
//                with multiple representations of the data. This is especially
//                useful for increasing the portability of documents cross-platform.
//
//                A part should verify that each kind is valid; that it exists in
//                the content property in the correct order; and then write the data.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__ExternalizeKinds
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODTypeList*                    kindset
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","ExternalizeKinds");

    SOM_TRY
        if ( !_fReadOnlyStorage )
        {
            // Get our storage unit.
            ODStorageUnit* storageUnit = _fSelf->GetStorageUnit(ev);

            // Verify that the storage unit has the appropriate properties
            // and values to allow us to run. If not, add them.
            somSelf->CheckAndAddProperties(ev, storageUnit);

            // Verify that there are no "bogus" values in the Content property.
            somSelf->CleanseContentProperty(ev, storageUnit);

            // Write out the part's state information.
            somSelf->ExternalizeStateInfo(ev, storageUnit, kODNULLKey, kODNULL);

            // Even if the kindset contains no types we support, we must at least
            // write out our preferred (and only) kind.
            somSelf->ExternalizeContent(ev, storageUnit, kODNULLKey, kODNULL);
        }
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        ChangeKind
// Origin:        ODPart
//
// Description:    This method is called when the user changes the part's primary
//                kind and/or when the part editor is switched via the Info dialog.
//                Don't write the properties/values/data until Externalize is called.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__ChangeKind
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODType                             kind
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","ChangeKind");

    SOM_TRY
        // PictureViewer has only one kind, but we need to make sure the
        // "Preferred Kind" property has the correct value. Check for
        // both the scrap kind and file kind, but only write out our
        // scrap kind.
        if ( ODISOStrEqual(kind, gGlobals->fPictScrapKind) ||
                ODISOStrEqual(kind, gGlobals->fPictFileKind) )
        {
            // Get our storage unit.
            ODStorageUnit* storageUnit = _fSelf->GetStorageUnit(ev);

            TRY
                // Write out the user's preferred kind.
                ODSetISOStrProp(ev, storageUnit, kODPropPreferredKind,
                                        kODISOStr, gGlobals->fPictScrapKind);

                // Changing our kind dirties our content.
                somSelf->SetDirty(ev);

                // Immediately externalize ourselves in the "new" format.
                somSelf->Externalize(ev);
            CATCH_ALL
                // Remove the property and value if something went wrong.
                ODSURemoveProperty(ev, storageUnit, kODPropPreferredKind);
            ENDTRY
        }
        else
            THROW(kODErrInvalidValueType);
    SOM_CATCH_ALL
    SOM_ENDTRY

}

//------------------------------------------------------------------------------
// Method:        CleanseContentProperty
// Origin:        PictureViewer
//
// Description:    This method is called during exteralization of the
//                part. The part should remove any value in the content
//                property that it cannot accurately write to.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__CleanseContentProperty
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODStorageUnit*                    storageUnit
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","CleanseContentProperty");

    ODULong numValues;
    ODULong index;

    SOM_TRY
        storageUnit->Focus(ev, kODPropContents, kODPosUndefined,
                                kODNULL, 0, kODPosAll);

        numValues = storageUnit->CountValues(ev);

        for ( index = numValues; index >= 1; index-- )
        {
            // Index from 1 to n through the values.
            storageUnit->Focus(ev, kODPropContents, kODPosUndefined,
                                    kODNULL, index, kODPosUndefined);

            // Get the ISO type name for the value. The temp object
            // will automatically delete the returned value when this
            // scope is exited.
            TempODValueType value = storageUnit->GetType(ev);

            // If the value type is not one we support, remove it.
            if ( !ODISOStrEqual(value, gGlobals->fPictScrapKind) )
                storageUnit->Remove(ev);
        }
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        UpdateFrame
// Origin:        PictureViewer
//
// Description:    Update the correct shape for the given frame.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__UpdateFrame
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODFrame*                    frame,
                ODTypeToken                    view,
                ODShape*                    usedShape
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","UpdateFrame");

    TRY
        // Update the frame to have the new view and usedShape.

        // Invalidate the old used shape.
        frame->Invalidate(ev, kODNULL, kODNULL);

        frame->SetViewType(ev, view);
        frame->ChangeUsedShape(ev, usedShape, kODNULL);

        // Invalidate the new used shape.
        frame->Invalidate(ev, kODNULL, kODNULL);
    CATCH_ALL
        // Failing isn't great, but we can live with it, so don't set ev.
    ENDTRY
}

//------------------------------------------------------------------------------
// Method:        CalculateUsedShape
// Origin:        PictureViewer
//
// Description:    This method is called in response to one of the display
//                frame's view being changed. The method calculates the
//                appropriate usedShape for the new view type.
//------------------------------------------------------------------------------
SOM_Scope    ODShape*
SOMLINK        PictureViewer__CalculateUsedShape
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","CalculateUsedShape");

    Rect        bounds;
    RgnHandle    usedRgn     = kODNULL;
    ODShape*    usedShape    = kODNULL;
    ODTypeToken view        = frame->GetViewType(ev);

    ODVolatile(usedShape);
    ODVolatile(usedRgn);

    SOM_TRY
        // If the view is "frame", we intentionally return a nil shape;
        // doing so, will reset the used shape to equal the frame shape.

        if ( view == gGlobals->fLargeIconView ||
                view == gGlobals->fSmallIconView ||
                view == gGlobals->fThumbnailView )
        {
            usedRgn = ODNewRgn();

            if ( view == gGlobals->fLargeIconView || view == gGlobals->fSmallIconView )
            {
                CUsingLibraryResources res;

                // Set the bounds rect for the icon size.
                SetRect(&bounds, 0, 0,
                            (view == gGlobals->fLargeIconView) ? kODLargeIconSize : kODSmallIconSize,
                            (view == gGlobals->fLargeIconView) ? kODLargeIconSize : kODSmallIconSize);

                // Convert the icon mask into a Region.
                THROW_IF_ERROR( IconIDToRgn(usedRgn, &bounds, atAbsoluteCenter, kBaseResourceID) );
            }
            else if ( view == gGlobals->fThumbnailView )
            {
                SetRect(&bounds, 0, 0, kODThumbnailSize, kODThumbnailSize);
                RectRgn(usedRgn, &bounds);
            }

            usedShape = frame->CreateShape(ev);
            usedShape->SetQDRegion(ev, usedRgn);
    }
    SOM_CATCH_ALL
        ODDisposeHandle((ODHandle)usedRgn);
        ODSafeReleaseObject(usedShape);
        usedShape = kODNULL;
    SOM_ENDTRY

    return usedShape;
}

//------------------------------------------------------------------------------
// Method:        CleanupWindow
// Origin:        PictureViewer
//
// Description:    This method is called by the part when a window needs to be
//                cleaned up for a frame being closed/removed.
//
//                The part deallocates the window buffer allocated in the
//                CreateWindow() method.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__CleanupWindow
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
    SampleCode_PictureViewerMethodDebug("PictureViewer","CleanupWindow");

       TRY
        CFrameInfo*    frameInfo = (CFrameInfo*)frame->GetPartInfo(ev);
        if ( frameInfo->ShouldDisposeWindow() )
        {
            TempODWindow window = frame->AcquireWindow(ev);
            THROW_IF_NULL(window);

            ODPlatformWindow windowPtr = window->GetPlatformWindow(ev);
            CloseWindow(windowPtr);
            ODDisposePtr(windowPtr);
        }
    CATCH_ALL
        somSelf->HandleDialogBox(ev, frame, kErrorBoxID, kErrWindowGone);
        // consume excpetion because it's not fatal.
    ENDTRY
}

//------------------------------------------------------------------------------
// Method:        GetDefaultWindowProperties
// Origin:        PictureViewer
//
// Description:    This method sets up the default properties for the window to
//                be created (called from the Open method).
//------------------------------------------------------------------------------
SOM_Scope    WindowProperties*
SOMLINK        PictureViewer__GetDefaultWindowProperties
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODFrame*                    sourceFrame,
                Rect*                        windowRect
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","GetDefaultWindowProperties");

    WindowProperties*    windowProperties;

    ODVolatile(windowProperties);

    SOM_TRY

        windowProperties = new WindowProperties;

        // Calculate the offset for the window based on the sourceFrame.
        if ( sourceFrame )
            somSelf->CalcPartWindowPosition(ev, sourceFrame, windowRect);
        else
            OffsetRect(windowRect, kALittleNudge,
                        GetMBarHeight() + kMacWindowTitleBarHeight);

        // Set the window bounds based on the calculated rect.
        windowProperties->boundsRect = *windowRect;

        // Get the part's name to use for the new window.
        TempODIText windowName = GetPartName(ev, _fSelf, kODCategoryDrawing);
        // Convert the ODIText into a Pascal string.
        GetITextString(windowName, windowProperties->title);

        // Fill in the other fields of the Window Properties struct.
        windowProperties->procID = zoomDocProc;
        windowProperties->hasCloseBox = kODTrue;
        windowProperties->refCon = (long)kODNULL;
        windowProperties->wasVisible = kODFalse;
        windowProperties->isResizable = kODTrue;
        windowProperties->isFloating = kODFalse;
        windowProperties->isRootWindow = sourceFrame ? kODFalse : kODTrue;
        windowProperties->shouldShowLinks = kODFalse;
        windowProperties->sourceFrame = sourceFrame;

    SOM_CATCH_ALL
        ODDeleteObject(windowProperties);
    SOM_ENDTRY

    return windowProperties;
}

//------------------------------------------------------------------------------
// Method:        GetSavedWindowProperties
// Origin:        PictureViewer
//
// Description:    This method is called from the Open method when the frame
//                 is the root frame of an existing document.
//------------------------------------------------------------------------------
SOM_Scope    WindowProperties*
SOMLINK        PictureViewer__GetSavedWindowProperties
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODFrame*                        frame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","GetSavedWindowProperties");

    RgnHandle             windowRgn = kODNULL;
    WindowProperties*     windowProperties;

    ODVolatile(windowRgn);
    ODVolatile(windowProperties);

   SOM_TRY
        windowProperties = new WindowProperties;

        // If we fail to load the window properties from storage, delete
        // the structure so the calling code will behave appropriately.
        if ( BeginGetWindowProperties(ev, frame, windowProperties) )
        {
            // Note: We don't call EndGetWindowProperties because it releases
            // the source frame, which we will need after this method returns.

            // Get the part's name to use for the new window.
            TempODIText windowName = GetPartName(ev, _fSelf, kODCategoryDrawing);
            // Convert the ODIText into a Pascal string.
            GetITextString(windowName, windowProperties->title);

            // Verify the window is still visible on a monitor.
            windowRgn = ODNewRgn();
            ODBoolean repositionWindow = kODFalse;

            // We are only concerned with the window's title bar being
            // visible, so calcuate the titlebar rect from the current
            // window bounds.
            Rect adjustedBounds = windowProperties->boundsRect;
            adjustedBounds.bottom = adjustedBounds.top;
            adjustedBounds.top -= kMacWindowTitleBarHeight;

            // Intersect the monitor's region
            RectRgn(windowRgn, &adjustedBounds);
            SectRgn(windowRgn, GetGrayRgn(), windowRgn);

            if ( !EmptyRgn(windowRgn) )
            {
                // If the visible portion of the window is too small, we need
                // to reposition it.
                Rect intersectedBounds = (**windowRgn).rgnBBox;
                if ( (intersectedBounds.right-intersectedBounds.left < kMinHorzVisPortion) ||
                        (intersectedBounds.bottom-intersectedBounds.top < kMinVertVisPortion) )
                    repositionWindow = kODTrue;
            }
            else
            {
                // If the window is completely offscreen, we need to reposition it.
                repositionWindow = kODTrue;
            }

            // Dispose of the allocated memory.
            ODDisposeHandle((ODHandle)windowRgn);
            windowRgn = kODNULL;

            // If not, we need to move it so the user can see it.
            if ( repositionWindow )
            {
                Rect windowRect = windowProperties->boundsRect;
                // Move the window to {0,0} coordinates.
                OffsetRect(&windowRect, -windowRect.left, -windowRect.top);
                // Now move the window to the default window position.
                OffsetRect(&windowRect, kALittleNudge, GetMBarHeight() + kMacWindowTitleBarHeight);
                // Save the new window position in our windowProperties.
                windowProperties->boundsRect = windowRect;
            }
        }
        else
        {
            // If we were unable to re-load window properties,
            // dispose of the struct.
            ODDeleteObject(windowProperties);
        }

    SOM_CATCH_ALL
        if ( windowRgn != kODNULL )
            ODDisposeHandle((ODHandle)windowRgn);
        ODDeleteObject(windowProperties);
    SOM_ENDTRY

    return windowProperties;
}

//------------------------------------------------------------------------------
// Method:        CheckAndAddProperties
// Origin:        PictureViewer
//
// Description:    This method is called to prepare the storage unit
//                during the creation of stationery, and to verify
//                that all the properties we need are present during
//                externalization. .
//
//                The part adds the default content property, a preferred editor
//                property (to aid in part binding), a display frames
//                property, and a display setting property (cropped/scaled).
//
// Note:        The function StorageUnitSetValue is a macro which
//                simplifies the use of ODByteArrary, which is required
//                in the StorageUnit interface. Look in StorUtil.h/cpp for
//                an example of using the ODByteArray struct.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__CheckAndAddProperties
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODStorageUnit*                storageUnit
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","CheckAndAddProperties");

    SOM_TRY

    // Create our content property.
    if ( !storageUnit->Exists(ev, kODPropContents, kODNULL, 0) )
        storageUnit->AddProperty(ev, kODPropContents);
    if ( !storageUnit->Exists(ev, kODPropContents, gGlobals->fPictScrapKind, 0) )
    {
        storageUnit->Focus(ev, kODPropContents, kODPosUndefined, kODNULL, 0, kODPosUndefined);
        storageUnit->AddValue(ev, gGlobals->fPictScrapKind);
    }

    // Since we are setting up the preferred kind property, we just write
    // out our default "kind" for the editor. We can write out the user
    // chosen kind in the ExternalizeStateInfo method.

    if ( !storageUnit->Exists(ev, kODPropPreferredKind, kODISOStr, 0) )
    {
        TRY
            ODSetISOStrProp(ev, storageUnit, kODPropPreferredKind, kODISOStr,
                                gGlobals->fPictScrapKind);
        CATCH_ALL
            // Remove the property and value if something went wrong.
            // OpenDoc looks at this value, so if not valid, be sure
            // it doesn't exist.
            ODSURemoveProperty(ev, storageUnit, kODPropPreferredKind);
        ENDTRY
    }

    // Add our display frame list.
    if ( !storageUnit->Exists(ev, kODPropDisplayFrames, kODNULL, 0) )
        storageUnit->AddProperty(ev, kODPropDisplayFrames);
    if ( !storageUnit->Exists(ev, kODPropDisplayFrames, kODWeakStorageUnitRefs, 0) )
    {
        storageUnit->Focus(ev, kODPropDisplayFrames, kODPosUndefined, kODNULL, 0, kODPosUndefined);
        storageUnit->AddValue(ev, kODWeakStorageUnitRefs);
    }

    // Add the display mode value (crop/scale).

    if ( !storageUnit->Exists(ev, kPropDisplayMode, kODNULL, 0) )
        storageUnit->AddProperty(ev, kPropDisplayMode);

    if ( !storageUnit->Exists(ev, kPropDisplayMode, kODSLong, 0) )
    {
        storageUnit->Focus(ev, kPropDisplayMode, kODPosUndefined, kODNULL, 0, kODPosUndefined);
        storageUnit->AddValue(ev, kODSLong);
    }

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        ReadPartInfo
// Origin:        ODPart
//
// Description:    When a frame is being internalized by the Draft, it will ask
//                the owner (part) to read in its info annotation on the frame.
//
//                The part info class knows how to internalize itself from a
//                storage unit view, so we just call InitFromStorage.
//------------------------------------------------------------------------------
SOM_Scope    ODInfoType
SOMLINK        PictureViewer__ReadPartInfo
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODFrame*                    frame,
                ODStorageUnitView*             storageUnitView
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","ReadPartInfo");

    CFrameInfo* frameInfo = new CFrameInfo(_fSession);

    SOM_TRY
        // Ask the info class to internalize itself.
        frameInfo->InitFromStorage(ev, storageUnitView);

        // We want to insure that frame negotiation only occurs once.
        // Thus, we set the flag to true since we are being internalized
        // from storage, meaning we've already performed frame negotiation
        // in the "FacetAdded" method.
        frameInfo->SetNegotiationFlag(kODTrue);

    SOM_CATCH_ALL
        // Clean up the allocated memory.
        ODDeleteObject(frameInfo);
    SOM_ENDTRY

    return (ODInfoType)frameInfo;
}

//------------------------------------------------------------------------------
// Method:        ClonePartInfo
// Origin:        ODPart
//
// Description:    When a frame is being cloned by the Draft, it will ask the owner
//                (part) to clone its info annotation on the frame.
//
//                The part uses a C++ helper class to encapsulate the information
//                we store with each frame, so we let it clone itself to the
//                storage unit view.
//------------------------------------------------------------------------------
SOM_Scope void
SOMLINK PictureViewer__ClonePartInfo
        (
            SampleCode_PictureViewer*    somSelf,
            Environment*                ev,
            ODDraftKey                     key,
            ODInfoType                     partInfo,
            ODStorageUnitView*             storageUnitView,
            ODFrame*                     scopeFrame
        )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","ClonePartInfo");

    SOM_TRY
        // Tell our frame info class to write itself out into the pre-
        // focused storage unit.
        ((CFrameInfo*)partInfo)->CloneInto(ev, key, storageUnitView, scopeFrame);
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        WritePartInfo
// Origin:        ODPart
//
// Description:    When a frame is being externalized by the Draft, it
//                will ask the owner (part) to write out its info
//                annotation on the frame.
//
//                The part info class knows how to externalize itself
//                to a storage unit view, so we just call Externalize.
//------------------------------------------------------------------------------
SOM_Scope void
SOMLINK PictureViewer__WritePartInfo
        (
            SampleCode_PictureViewer*    somSelf,
            Environment*                ev,
            ODInfoType                    partInfo,
            ODStorageUnitView*            storageUnitView
        )
{
    SampleCode_PictureViewerMethodDebug("PictureViewer","WritePartInfo");

    SOM_TRY
        // Tell our frame info class to write itself out to
        // the pre-focused storage unit.
        ((CFrameInfo*)partInfo)->Externalize(ev, storageUnitView);
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        Open
// Origin:        ODPart
//
// Description:    This method is called when OpenDoc, a containing part, or
//                the active editor/viewer would like to open a frame into
//                a seperate window. If a source frame is passed into
//                this method, the editor/viewer is being asked to open a
//                part window.
//
//                The part first checks to see if the display frame has
//                been opened into a window before (this will be true
//                if a source frame is passed into the method and if
//                the source frame has a valid window ID). If there is
//                already a window displaying the frame, just bring that
//                window to the front. If not, we create a window from
//                scratch and display it.
//------------------------------------------------------------------------------
SOM_Scope    ODID
SOMLINK        PictureViewer__Open
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","Open");

    ODID                windowID = kODNULLID;
    TempODWindow        window(kODNULL);
    WindowProperties*    windowProperties = kODNULL;
    ODBoolean            adjustShape = kODFalse;

    ODVolatile(windowProperties);

    SOM_TRY
        // Because the frame parameter being passed to us can be one of
        // three things, we must determine what it is; either the root
        // frame of an existing document, the source frame for a part
        // window, or null if we are opening a new document.

        if ( frame == kODNULL )
        {
            // Calculate the bounding rectangle for a new window
            Rect windowRect = somSelf->CalcPartWindowSize(ev, kODNULL);
            // Get the default setting for a document window.
            windowProperties = somSelf->GetDefaultWindowProperties(ev, kODNULL, &windowRect);
            // Create a Mac Window and register it with OpenDoc.
            window = somSelf->CreateWindow(ev, kODNULL, kODFrameObject, windowProperties);
        }
        else if ( frame->IsRoot(ev) )
        {
            // Get the previously saved settings for the document window.
            windowProperties = somSelf->GetSavedWindowProperties(ev, frame);

            if ( windowProperties == kODNULL )
            {
                // Calculate the bounding rectangle for a new window
                Rect windowRect = somSelf->CalcPartWindowSize(ev, frame);
                // Get the default setting for a document window.
                windowProperties = somSelf->GetDefaultWindowProperties(ev, kODNULL, &windowRect);
            }

            // Set the adjustShape flag to true so the window will be adjusted later.
            adjustShape = kODTrue;

            // Create a Mac Window and register it with OpenDoc.
            window = somSelf->CreateWindow(ev, frame, kODFrameObject, windowProperties);

            // We release the source frame here because we didn't call
            // EndGetWindowProperties and becuase we are done with it.
            ODReleaseObject(ev, windowProperties->sourceFrame);
        }
        else // frame is a source frame
        {
            window = somSelf->AcquireFramesWindow(ev, frame);

            if ( window == kODNULL )
            {

                // Calculate the bounding rectangle for a new window
                Rect windowRect = somSelf->CalcPartWindowSize(ev, frame);

                // Get the default setting for a document window.
                windowProperties = somSelf->GetDefaultWindowProperties(ev, frame, &windowRect);

                // Create a Mac Window and register it with OpenDoc.
                window = somSelf->CreateWindow(ev, kODNULL, kODFrameObject, windowProperties);

                // Tell the source frame that it is opened in a part window.
                CFrameInfo* frameInfo = (CFrameInfo*)frame->GetPartInfo(ev);
                frameInfo->SetPartWindow(ev, window);
            }
        }

        if ( window )
        {
            window->Open(ev);

            // The following is needed in cases such as drag and drop to the
            // Finder. The window needs to adjust its shape and clip shape.
            if ( adjustShape )
                window->AdjustWindowShape(ev);

            // Make the window visible.
            window->Show(ev);
            // Activate and select the window.
            window->Select(ev);

            // Get window id for return result.
            windowID = window->GetID(ev);
        }

        // Cleanup allocated memory.
        ODDeleteObject(windowProperties);

    SOM_CATCH_ALL
        // If we threw early, the source frame's refcount may be too high.
        if ( windowProperties )
            ODSafeReleaseObject(windowProperties->sourceFrame);
        // Cleanup the created items.
        ODDeleteObject(windowProperties);
        windowID = kODNULLID;
    SOM_ENDTRY

    return windowID;
}

//------------------------------------------------------------------------------
// Method:        DisplayFrameAdded
// Origin:        ODPart
//
// Description:    This method is called in response to a frame being
//                created for our part.
//
//                The part records the existence of a new display frame
//                in its internal display frame list, and verifies that
//                the frame is set up correctly (eg, valid viewType).
//                The part also creates and stores its frame info class
//                in the new frame.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__DisplayFrameAdded
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","DisplayFrameAdded");

    SOM_TRY
        // If we are being embedded in another part, the presentation field
        // will (most likely) be unset; we need to set it to something meaningful.
        // The view field may also be unset; if so, we prefer to be displayed
        // in a frame view.

        if ( frame->GetPresentation(ev) != gGlobals->fMainPresentation )
            frame->SetPresentation(ev, gGlobals->fMainPresentation);

        if ( frame->GetViewType(ev) == kODNullTypeToken )
            frame->SetViewType(ev, gGlobals->fFrameView);

        // Hang our state info off of the new display frame. We use the
        // CFrameInfo object for activation, updating, and window maintenance.
        CFrameInfo* frameInfo = new CFrameInfo(_fSession);
        frame->SetPartInfo(ev, (ODInfoType)frameInfo);

        // If the frame being added is a root frame, we know that a window
        // is associated with this frame. Notify ourselves that we need to
        // clean it up when the frame goes away.
        if ( frame->IsRoot(ev) )
            frameInfo->SetShouldDisposeWindow(kODTrue);

        // The proxy class will refcount the frame passed to it, so we
        // don't need to worry about refcounting the display frame.
        CFrameProxy* proxy = new CFrameProxy;
        proxy->InitFrameProxy(ev,frame);

        // Add the proxy to the display frame collection.
        _fDisplayFrames->Add(proxy);

        // Since we maintain a persistent list of weak references to our
        // display frames, having one added to the part dirties it.
        somSelf->SetDirty(ev);
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        DisplayFrameRemoved
// Origin:        ODPart
//
// Description:    This method is called in response to a frame being
//                removed from our part.
//
//                The part removes the frame from its internal display
//                frame list and relinquishes any foci that it still owns. Lastly,
//                if the frame has a source frame (it was the root frame of a
//                part window), we will record the part window bounds so that
//                any subsequent part windows opened on the source frame will
//                appear in the same location.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__DisplayFrameRemoved
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODFrame*                        frame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","DisplayFrameRemoved");

    SOM_TRY
        CFrameInfo* frameInfo = (CFrameInfo*)frame->GetPartInfo(ev);

        // Make sure the frame going away does not own any foci. Forgetting
        // to do this, will cause a refcounting error when the frame
        // is deleted by the draft.
        somSelf->RelinquishAllFoci(ev, frame);

        // Clean up the display frame.
        somSelf->CleanupDisplayFrame(ev, frame, kFrameRemoved);
        // Clean up any associated window.
        somSelf->CleanupWindow(ev, frame);

        // Dispose of the frame's runtime state info.
        frame->SetPartInfo(ev, (ODInfoType) kODNULL);
        ODDeleteObject(frameInfo);

        // Remove the display frame from our collection.
        CListIterator fiter(_fDisplayFrames);
        for ( CFrameProxy* proxy = (CFrameProxy*)fiter.First();
                fiter.IsNotComplete(); proxy = (CFrameProxy*)fiter.Next() )
        {
            if ( ODObjectsAreEqual(ev, proxy->GetFrame(ev), frame) )
            {
                // Delete the proxy object and its contents. The frame's
                // refcount will be decremented in the proxy destructor.
                fiter.RemoveCurrent();
                delete proxy;
            }
        }

        // Since we maintain a persistent list of weak references to our
        // display frames, having one removed from the part dirties it.
        somSelf->SetDirty(ev);
    SOM_CATCH_ALL
        // Alert the user of the problem.
        somSelf->HandleDialogBox(ev, frame, kErrorBoxID, kErrRemoveFrame);
        // Change the error code value so the DocShell doesn't
        // display an error dialog.
        SetErrorCode(kODErrAlreadyNotified);
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        DisplayFrameClosed
// Origin:        ODPart
//
// Description:    This method is called in response to a frame being
//                closed (not removed).
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__DisplayFrameClosed
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","DisplayFrameClosed");

    SOM_TRY
        // Make sure the frame going away does not own any foci. Forgetting
        // to do this, will cause a refcounting error when the frame is
        // deleted by the draft.
        somSelf->RelinquishAllFoci(ev, frame);

        // Clean up the display frame.
        somSelf->CleanupDisplayFrame(ev, frame, kFrameClosed);
        // Clean up any associated window.
        somSelf->CleanupWindow(ev, frame);
        // Dispose of the frame's runtime state info.
        CFrameInfo* frameInfo = (CFrameInfo*)frame->GetPartInfo(ev);
        frame->SetPartInfo(ev, (ODInfoType)kODNULL);
        ODDeleteObject(frameInfo);

        // Remove the display frame from our collection.
        CListIterator fiter(_fDisplayFrames);
        for ( CFrameProxy* proxy = (CFrameProxy*)fiter.First();
                fiter.IsNotComplete(); proxy = (CFrameProxy*)fiter.Next() )
        {
            if ( proxy->GetID() == frame->GetID(ev) )
            {
                // Release the frame reference, but don't get rid of the
                // proxy object because "closed" frames may be reconnected
                // before the document is really closed.
                proxy->Purge(ev);
            }
        }

    SOM_CATCH_ALL
        // Alert the user of the problem.
        somSelf->HandleDialogBox(ev, frame, kErrorBoxID, kErrRemoveFrame);
        // Change the error code value so the DocShell doesn't
        // display an error dialog.
        SetErrorCode(kODErrAlreadyNotified);
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        DisplayFrameConnected
// Origin:        ODPart
//
// Description:    This method is called when a display frame (ours or another
//                part's), was previously written out and is now being
//                internalized. It will be another part's data in instances
//                such as editor swapping. This methodis called instead of
//                DisplayFrameAdded because a "new"frame is not being created;
//                an existing one is being reconstituted.
//
//                The part first checks to see if it can match its frame to an
//                ID in the Display frame list; if so, it puts the frame into the
//                proxy. If not, we create a new proxy and then add the frame.
//
// Warning:        This method may be called during editor swapping, with a frame
//                not recognized by the part. This is okay. Just treat the case
//                as if a "new" frame were being added to the part.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__DisplayFrameConnected
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","DisplayFrameConnected");

    SOM_TRY

    // Iterate over our display collection to match the frame with
    // an existing proxy with the correct frame ID. If we find it,
    // replace the ID with the actual frame. If we don't find it,
    // treat it as a newly "added" frame.
    ODBoolean found = kODFalse;
    CListIterator fiter(_fDisplayFrames);
    for ( CFrameProxy* proxy = (CFrameProxy*) fiter.First();
            fiter.IsNotComplete() && !found;
            proxy = (CFrameProxy*) fiter.Next() )
    {
        if ( proxy->GetID() == frame->GetID(ev) )
        {
            // The proxy class will refcount the frame passed to it, so we
            // don't need to worry about refcounting the display frame.
            proxy->SetFrame(ev, frame);
            found = kODTrue;
        }
    }

    // Parts typically operate under the assumption that they have previous
    // knowledge of a frame before it is connected to them. This knowledge
    // should come from having read in the frame reference when the part
    // was internalized. If the frame is an "unknown", the part was probably
    // bound to another editor's storage unit because the editor is missing or
    // the user changed the editor in the Info dialog.
    if ( found )
    {
        // If a display frame is connected to us with an unrecognizable
        // presentation, we need to set it to something meaningful.

        if ( frame->GetPresentation(ev) != gGlobals->fMainPresentation )
            frame->SetPresentation(ev, gGlobals->fMainPresentation);

        if ( frame->IsRoot(ev) )
        {
            // If the frame being added is a root frame, we know that a window
            // is associated with this frame. Notify ourselves that we need to
            // clean it up when the frame goes away.
            CFrameInfo* frameInfo = (CFrameInfo*) frame->GetPartInfo(ev);
            frameInfo->SetShouldDisposeWindow(kODTrue);

            // In addition, we need to verify that the frame is in "frame" view.
            // If the user dragged an icon from a document to Finder and then
            // opens the resultant document, the view would be "icon". However,
            // displaying an icon is useless, so we need to change the view to
            // frame.

            // NOTE: we first check to see if the view type is set
            // to "frame" view. If not, we set it. We perform this check
            // rather than just setting it in all instances, because that
            // would be costly.
            if ( frame->GetViewType(ev) != gGlobals->fFrameView )
                frame->SetViewType(ev, gGlobals->fFrameView);
        }
    }
    else
    {
        // If an unrecognizable frame is connected to us, treat it like a "new"
        // frame and call our method to add it.
        somSelf->DisplayFrameAdded(ev, frame);
    }

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        CleanupDisplayFrame
// Origin:        PictureViewer
//
// Description:    This method is called when a frame has been closed or removed.
//                The method cleans up the references and state information stored
//                in the CFrameInfo class.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__CleanupDisplayFrame
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODFrame*                        frame,
                ODBoolean                        frameRemoved
            )
{
    SampleCode_PictureViewerMethodDebug("PictureViewer","CleanupDisplayFrame");

    ODError        error = noErr;
    CFrameInfo*    frameInfo = (CFrameInfo*)frame->GetPartInfo(ev);

    TRY
        // If we are the root of a child window, we need to notify
        // our source frame that we are going away.
        if ( frameInfo->HasSourceFrame() )
        {
            ODFrame* sourceFrame = frameInfo->GetSourceFrame(ev);
            CFrameInfo* sourceFrameInfo = (CFrameInfo*)sourceFrame->GetPartInfo(ev);

            if ( frameRemoved )
            {
                // Invalidate the source frame. We do this because the
                // source frame may have a unique display when it has
                // been opened into a part window. This forces the
                // frame to redraw "not opened".
                sourceFrame->Invalidate(ev, kODNULL, kODNULL);
            }

            // Tell the source frame that its dependent is going away.
            sourceFrameInfo->ReleaseDependentFrame(ev);

            // Release our reference to the source frame.
            frameInfo->ReleaseSourceFrame(ev);

            // If the frame is the root, it is a part window going away
            // and we need to notify our source frame that it no longer
            // has a part window.
            if ( frame->IsRoot(ev) )
                sourceFrameInfo->SetPartWindow(ev, kODNULL);
        }
    CATCH_ALL
        error = ErrorCode();
    ENDTRY

    TRY
        // If the frame was removed from the document, we need to remove
        // any child window displaying that frame.
        if ( frameRemoved )
        {
            // If we have a child window, we need to close it.
            ODWindow* window = frameInfo->AcquirePartWindow(ev);

            if ( window )
            {
                frameInfo->SetPartWindow(ev, kODNULL);
                window->CloseAndRemove(ev);
            }
        }
    CATCH_ALL
        error = ErrorCode();
    ENDTRY

    TRY
        if ( frameInfo->HasDependentFrame() )
        {
            // Get the frame that is dependent on this one. We can safely
            // do this because we only reference our own display frames.
            ODFrame* dependentFrame = frameInfo->GetDependentFrame(ev);
            CFrameInfo* dependentFrameInfo = (CFrameInfo*)dependentFrame->GetPartInfo(ev);

            // Tell the dependent frame that its source is going away.
            dependentFrameInfo->ReleaseSourceFrame(ev);

            // Release our reference to the dependent frame.
            frameInfo->ReleaseDependentFrame(ev);
        }
    CATCH_ALL
        error = ErrorCode();
    ENDTRY

    // If anything went wrong, signal an error.
    THROW_IF_ERROR(error);
}

//------------------------------------------------------------------------------
// Method:        FrameShapeChanged
// Origin:        ODPart
//
// Description:    This method is called in response to a frame's shape being
//                altered, either by the user or the part we are embedded in.
//
//                To keep all dependent frames in sync, we need to propogate the
//                new frame shape to the frames dependent on the changed frame.
//                This is done by observing the display frames stored in the
//                frame info and calling RequestFrameShape for each.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__FrameShapeChanged
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODFrame*                        frame
            )
{
    SampleCode_PictureViewerMethodDebug("PictureViewer","FrameShapeChanged");

    SOM_TRY
        // Adjust the "used" shape for the new frame shape.
        TempODShape usedShape = somSelf->CalculateUsedShape(ev, frame);
        frame->ChangeUsedShape(ev, usedShape, kODNULL);
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        FacetAdded
// Origin:        ODPart
//
// Description:    This method is called when any part adds a facet to
//                one of our display frames.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__FacetAdded
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODFacet*                    facet
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","FacetAdded");

    SOM_TRY
        ODTypeToken    viewType;
        ODBoolean    isNegotiated;        // true if frame already negotiated
        ODFrame*    frame = facet->GetFrame(ev);
        CFrameInfo* frameInfo = (CFrameInfo*)frame->GetPartInfo(ev);

        viewType = frame->GetViewType(ev);
        isNegotiated = frameInfo->GetNegotiationFlag();

        if ( viewType == gGlobals->fFrameView && _fPicture && !isNegotiated )
        {
            // Perform frame negotiation to receive a frame shape
            // that will contain the picture.

            Rect        bounds;
            ODRect        pictRect;

            bounds = (**((PicHandle)_fPicture)).picFrame;
            OffsetRect(&bounds, -bounds.left, -bounds.top);

            IntToFixedRect(bounds, pictRect);

            TempODShape    wantShape = frame->CreateShape(ev);
            wantShape->SetRectangle(ev, &pictRect);

            TempODShape result = frame->RequestFrameShape(ev, wantShape, kODNULL);

            // Notify the frame of the new shape
            frame->Invalidate(ev, kODNULL, kODNULL);

            frameInfo->SetNegotiationFlag(kODTrue);
        }

        // If a root facet is being added, the frame should be activated when the
        // window is "selected". This prevents OpenDoc from getting into an
        // ambiguous state of no part having the selection focus.

        if ( frame->IsRoot(ev) )
        {
            frameInfo->SetActiveFacet(facet);
            frameInfo->SetFrameReactivate(kODTrue);
        }

        // If a frame had all of its facets removed, the frame would have
        // hidden any of its part windows. If the frame becomes visible again,
        // by having a facet added to it, we will "show" the part window for
        // the frame.

        if ( (CountFacets(ev, frame) == 1) )
        {
            TempODWindow window = frameInfo->AcquirePartWindow(ev);
            if ( window )
                window->Show(ev);
        }
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        FacetRemoved
// Origin:        ODPart
//
// Description:    This method is called when any part removes a facet from
//                one of our display frames.
//
//                The part just removes the "active" flag from the appropriate
//                display frame if necessary since this facet will not be
//                available, or active, again.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__FacetRemoved
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODFacet*                        facet
            )
{
    SampleCode_PictureViewerMethodDebug("PictureViewer","FacetRemoved");

    ODFrame*    frame = facet->GetFrame(ev);
    CFrameInfo* frameInfo = (CFrameInfo*)facet->GetFrame(ev)->GetPartInfo(ev);
    TempODFrame    containingFrame = frame->AcquireContainingFrame(ev);

    SOM_TRY
        // If the facet was the active facet, it can no longer be.
        if ( ODObjectsAreEqual(ev, frameInfo->GetActiveFacet(), facet) )
            frameInfo->SetActiveFacet(kODNULL);

        // If a frame has all of its facets removed and its containing frame set
        // to NULL, the frame becomes "hidden". If the frame owns a part window,
        // the part window should also be hidden.

        if ( (CountFacets(ev, frame) == 0) && containingFrame == kODNULL )
        {
            TempODWindow window = frameInfo->AcquirePartWindow(ev);
            if ( window )
                window->Hide(ev);
        }
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        AttachSourceFrame
// Origin:        ODPart
//
// Description:    If a part which we are contained in is opened into a part
//                window, it is required to iterate over its embedded frames and
//                add new display frames in the part window. After each new
//                embedded frame is created, this method will be called.
//
//                We just validate the frame in this part.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__AttachSourceFrame
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODFrame*                    frame,
                ODFrame*                    sourceFrame
            )
{
    SampleCode_PictureViewerMethodDebug("PictureViewer","AttachSourceFrame");

    SOM_TRY
        // Tell the new frame about its source.
        CFrameInfo* frameInfo = (CFrameInfo*)frame->GetPartInfo(ev);
        frameInfo->SetSourceFrame(ev, sourceFrame);

        // And tell the source about its new dependent.
        frameInfo = (CFrameInfo*)sourceFrame->GetPartInfo(ev);
        frameInfo->SetDependentFrame(ev, frame);

        // In both cases, refcounting of the frame and sourceFrame is
        // handled by the CFrameInfo class.
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        ViewTypeChanged
// Origin:        ODPart
//
// Description:    This method is called when one of our display frame's viewType
//                field has been modified. We call this method on ourselves when
//                new display frames are added, but it can also be called when
//                the user changes the view in the "part info" dialog.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__ViewTypeChanged
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODFrame*                        frame
            )
{
    SampleCode_PictureViewerMethodDebug("PictureViewer","ViewTypeChanged");

    SOM_TRY
        // Change this frame's used shape to match the new view setting.
        TempODShape newUsedShape = somSelf->CalculateUsedShape(ev, frame);

        frame->Invalidate(ev, kODNULL, kODNULL);
        frame->ChangeUsedShape(ev, newUsedShape, kODNULL);
        frame->Invalidate(ev, kODNULL, kODNULL);
    SOM_CATCH_ALL
            frame->SetViewType(ev, gGlobals->fFrameView);
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        Draw
// Origin:        ODPart
//
// Description:    This method is called when a facet of a part's display
//                frame intersects the invalidated portion of an OpenDoc
//                window. The invalidShape parameter passed in is the
//                portion of the facet which has been invalidated.
//
//                The part sets up the drawing environment and then calls the
//                appropriate drawing method based on the frame's viewType.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__Draw
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODFacet*                    facet,
                ODShape*                    invalidShape
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","Draw");

    SOM_TRY
        // Focus the port and origin for drawing in our facet.
        // Note that this instance of the CFocus class is being
        // allocated on the stack. When the execution leaves the
        // scope of this method, the destructor (which cleans up
        // the drawing environment) is automatically called.

        CFocus initiateDrawing(ev, facet, invalidShape);

        ODTypeToken view = facet->GetFrame(ev)->GetViewType(ev);

        if ( view == gGlobals->fLargeIconView || view == gGlobals->fSmallIconView )
            somSelf->DrawIconView(ev, facet);
        else if ( view == gGlobals->fThumbnailView )
            somSelf->DrawThumbnailView(ev, facet);
        else
            somSelf->DrawFrameView(ev, facet);
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        DrawFrameView
// Origin:        PictureViewer
//
// Description:    This method is called by the part when the frame being
//                drawn is in "frame" view.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__DrawFrameView
             (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODFacet*                        facet
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","DrawFrameView");

    SOM_TRY
        if ( _fPicture )
        {
            GrafPtr        port;
            Rect         bounds;

            GetPort(&port);
            //• An optimization here would be to erase the
            //  difference between the picture and clip shape.
            EraseRect(&port->portRect);

            if ( _fDisplayMode == kCommandScale )
            {
                TempODShape frameShape = facet->GetFrame(ev)
                                        ->AcquireFrameShape(ev, kODNULL);

                RgnHandle rgn = frameShape->GetQDRegion(ev);
                bounds = (**rgn).rgnBBox;
                OffsetRect(&bounds, -bounds.left, -bounds.top);
                DrawPicture((PicHandle)_fPicture, &bounds);
            }
            else
            {
                bounds = (**((PicHandle)_fPicture)).picFrame;
                OffsetRect(&bounds, -bounds.left, -bounds.top);
                DrawPicture((PicHandle)_fPicture, &bounds);
            }
        }
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        DrawIconView
// Origin:        PictureViewer
//
// Description:    This method is called by the part when the frame being
//                drawn is in "standard icon" view.
//
//                The part uses the Icon Utilities toolbox manager to
//                aid in drawing icons in active windows. The Guidelines
//                require a different appearance for selected icons in
//                inactive windows, which we do manually.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__DrawIconView
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODFacet*                        facet
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","DrawIconView");

    Rect                iconRect;
    IconTransformType     transformType = ttNone;
    CFrameInfo*            frameInfo;
    ODFrame*            frame;
    ODTypeToken            viewType;

    SOM_TRY
        frame        = facet->GetFrame(ev);
        viewType    = frame->GetViewType(ev);
        frameInfo     = (CFrameInfo*)frame->GetPartInfo(ev);

        // Check to see if the facet is selected
        if ( facet->GetHighlight(ev) == kODFullHighlight )
            transformType = ttSelected;

        // Check to see if the frame has been opened into a part window.
        TempODWindow window = frameInfo->AcquirePartWindow(ev);
        if ( window && window->IsShown(ev) )
            transformType |= ttOpen;

        // Draw the icon.
        if ( viewType == gGlobals->fLargeIconView )
            SetRect(&iconRect, 0, 0, kODLargeIconSize, kODLargeIconSize);
        else // ( viewType == gGlobals->fSmallIconView )
            SetRect(&iconRect, 0, 0, kODSmallIconSize, kODSmallIconSize);

        CUsingLibraryResources res;
        PlotIconID(&iconRect, atAbsoluteCenter, transformType, kBaseResourceID);
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        DrawThumbnailView
// Origin:        PictureViewer
//
// Description:    This method is called by the part when the frame being
//                drawn in is in "thumbnail" view.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__DrawThumbnailView
             (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODFacet*                    facet
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","DrawThumbnailView");

    SOM_TRY
        // If our thumbnail representation doesn't exist, try
        // recreating it.
        if ( !_fGWorld )
            somSelf->GenerateThumbnail(ev, facet->GetFrame(ev));

        if ( _fGWorld )
            DrawGWorldThumbnail(ev, (GWorldPtr)_fGWorld, facet);
        else
        {    // Offscreen gWorld not available. Just draw it.
            Rect    bounds;

            SetRect(&bounds, 0, 0, kODThumbnailSize, kODThumbnailSize);
            DrawPicture((PicHandle)_fPicture, &bounds);
        }
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        BeginRelinquishFocus
// Origin:        ODPart
//
// Description:    This method is called when another part (or possibly
//                ourself) is requesting a focus for one of its display
//                frames. Returning true means we are willing to give
//                up the requested focus.
//
//                The part will give up any focus except for the
//                modal focus. We don't want to give this up until we
//                are completely done displaying a modal dialog.
//------------------------------------------------------------------------------
SOM_Scope    ODBoolean
SOMLINK        PictureViewer__BeginRelinquishFocus
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODTypeToken                        focus,
                ODFrame*                        /*ownerFrame*/,
                ODFrame*                        proposedFrame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","BeginRelinquishFocus");

    ODBoolean willRelinquish = kODTrue;

    SOM_TRY
        // Another part is trying to put up a Modal dialog while we
        // are currently displaying ours. Deny the request.
        if ( focus == gGlobals->fModalFocus )
        {
            TempODPart proposedPart = ODAcquirePart(ev,proposedFrame);
            if ( ODObjectsAreEqual(ev, proposedPart, _fSelf) == kODFalse )
                willRelinquish = kODFalse;
        }
    SOM_CATCH_ALL
        willRelinquish = kODFalse;
    SOM_ENDTRY

    return willRelinquish;
}

//------------------------------------------------------------------------------
// Method:        CommitRelinquishFocus
// Origin:        ODPart
//
// Description:    This method is called when it is actually time to give
//                up the requested focus.
//
//                The part calls its FocusLost method to handle the
//                reliquishing of the particular focus.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__CommitRelinquishFocus
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODTypeToken                        focus,
                ODFrame*                        ownerFrame,
                ODFrame*                        proposedFrame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","CommitRelinquishFocus");

    SOM_TRY
        // We agreed to give up the requested focus, so now we must do so.
        somSelf->FocusLost(ev, focus, ownerFrame);
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        AbortRelinquishFocus
// Origin:        ODPart
//
// Description:    This method is called when another part (or ourself) requested
//                a focus for one of its display frames, bet we returned kODFalse
//                from BeginRelinqishFocus() for one, or all, of the requested
//                foci. At this point, we are being told to resume ownership of
//                the focus.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__AbortRelinquishFocus
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODTypeToken                        focus,
                ODFrame*                        ownerFrame,
                ODFrame*                        /*proposedFrame*/
            )
{
    SampleCode_PictureViewerMethodDebug("PictureViewer","AbortRelinquishFocus");

    // Some parts may have suspended some events in the BeginRelinquishFocus
    // method. If so, they would resume those events here.
}

//------------------------------------------------------------------------------
// Method:        FocusAcquired
// Origin:        ODPart
//
// Description:    This method is called when the Arbitrator has
//                registered us as the "owner" of the particular focus.
//                This can occur if a focus is requested, or if a focus
//                is tranferred to one of the part's display frames.
//
//                The part will request its complete focus set to become active.
//                If the part is successful, we notify ourself to become active.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__FocusAcquired
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODTypeToken                        focus,
                ODFrame*                        ownerFrame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","FocusAcquired");

    ODArbitrator* arbitrator =  _fSession->GetArbitrator(ev);

    SOM_TRY
        if ( arbitrator->RequestFocusSet(ev, gGlobals->fUIFocusSet, ownerFrame) )
        {
            somSelf->PartActivated(ev, ownerFrame);
        }
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        FocusLost
// Origin:        ODPart
//
// Description:    This method is called when the Arbitrator has
//                unregistered us as the owner of a particular focus.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__FocusLost
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODTypeToken                    focus,
                ODFrame*                    ownerFrame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","FocusLost");

    SOM_TRY
        if ( focus == gGlobals->fSelectionFocus )
        {
            CFrameInfo* frameInfo = (CFrameInfo*)ownerFrame->GetPartInfo(ev);
            frameInfo->SetFrameActive(kODFalse);
        }
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        RelinquishAllFoci
// Origin:        PictureViewer
//
// Description:    This method is called when a frame is going away. The method
//                relinquishes all foci the frame owns.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__RelinquishAllFoci
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODFrame*                        frame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","RelinquishAllFoci");

    ODArbitrator* arbitrator = _fSession->GetArbitrator(ev);

    TRY
        TempODFrame focusFrame = arbitrator->AcquireFocusOwner(ev, gGlobals->fSelectionFocus);
        if ( ODObjectsAreEqual(ev, focusFrame, frame) )
        {
            arbitrator->RelinquishFocus(ev, gGlobals->fSelectionFocus, frame);
            somSelf->FocusLost(ev, gGlobals->fSelectionFocus, frame);
        }
    CATCH_ALL
    ENDTRY

    TRY
        TempODFrame focusFrame = arbitrator->AcquireFocusOwner(ev, gGlobals->fMenuFocus);
        if ( ODObjectsAreEqual(ev, focusFrame, frame) )
        {
            arbitrator->RelinquishFocus(ev, gGlobals->fMenuFocus, frame);
            somSelf->FocusLost(ev, gGlobals->fMenuFocus, frame);
        }
    CATCH_ALL
    ENDTRY

    TRY
        TempODFrame focusFrame = arbitrator->AcquireFocusOwner(ev, gGlobals->fClipboardFocus);
        if ( ODObjectsAreEqual(ev, focusFrame, frame) )
        {
            arbitrator->RelinquishFocus(ev, gGlobals->fClipboardFocus, frame);
            somSelf->FocusLost(ev, gGlobals->fClipboardFocus, frame);
        }
    CATCH_ALL
    ENDTRY
}

//------------------------------------------------------------------------------
// Method:        CloneInto
// Origin:        ODPersistentObject
//
// Description:    This method is called during cloning, typically during data
//                Interchange operations. The part should write out its current
//                state information and contents into the storage unit passed in.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__CloneInto
             (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODDraftKey                        key,
                ODStorageUnit*                    destinationSU,
                ODFrame*                        initiatingFrame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","CloneInto");

    SOM_TRY
        // This calls back up to the persistent object parent class
        // which copies over our timedate stamp and last modified info.
        SampleCode_PictureViewer_parent_ODPart_CloneInto(somSelf,ev, key, destinationSU, initiatingFrame);

        // If we haven't written out to this storage unit, externalize the
        // current state and contents.

        if ( !destinationSU->Exists(ev, kODPropContents, gGlobals->fPictScrapKind, 0) )
        {
            // Add the properties we need to successfully externalize
            // ourselves into the destination storage unit.
            somSelf->CheckAndAddProperties(ev, destinationSU);

            // Write out the part's state information.
            somSelf->ExternalizeStateInfo(ev, destinationSU, key, initiatingFrame);

            // Write out the part's content.
            somSelf->ExternalizeContent(ev, destinationSU, key, initiatingFrame);
        }
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        HandleEvent
// Origin:        ODPart
//
// Description:    The method is called when an event occurs within one of
//                our owned foci. The exception to this case are "mouse
//                movement" events and embedded frame events, which can occur
//                when a part owns no foci.
//
//                The part returns true if the event was handled.
//------------------------------------------------------------------------------
SOM_Scope    ODBoolean
SOMLINK        PictureViewer__HandleEvent
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODEventData*                    event,
                ODFrame*                        frame,
                ODFacet*                        facet,
                ODEventInfo*                    eventInfo
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","HandleEvent");

    ODBoolean    eventHandled = kODFalse;

    // Event handling is basically the same as standard Macintosh applications,
    // except that the events have been renamed for cross-platform compatability.

    SOM_TRY
        switch(event->what)
        {
            case kODEvtMouseDown:
            case kODEvtMouseUp:
                eventHandled = somSelf->HandleMouseEvent(ev, event, facet, eventInfo);
                break;

            case kODEvtMenu:
                eventHandled = somSelf->HandleMenuEvent(ev, event, frame);
                break;

            case kODEvtActivate:
                // We are being notified that a window we are displayed in has
                // just been activated/deactivated (hilighted/unhilighted).
                somSelf->WindowActivating(ev, frame, (event->modifiers & activeFlag));
                eventHandled = kODTrue;
                break;

            case kODEvtMouseEnter:
            case kODEvtMouseLeave:
                SetCursor(&ODQDGlobals.arrow);
                eventHandled = kODTrue;
                break;

            case kODEvtMouseWithin:
                eventHandled = kODTrue;
                break;

            // Other events a part might handle:
            case kODEvtNull:
            case kODEvtMouseDownEmbedded:
            case kODEvtMouseUpEmbedded:
            case kODEvtMouseDownBorder:
            case kODEvtMouseUpBorder:
            case kODEvtWindow:
            case kODEvtKeyUp:
            case kODEvtKeyDown:
            case kODEvtAutoKey:
            case kODEvtDisk:
            case kODEvtOS:
            default:
                break;
        }
    SOM_CATCH_ALL
    SOM_ENDTRY

    return eventHandled;
}

//------------------------------------------------------------------------------
// Method:        AdjustMenus
// Origin:        ODPart
//
// Description:    This method is called when a kODEvtMouseDown event occurs in
//                the menubar and when the part owns the "menu" focus, or when
//                the root part of a document.
//
//                The part first verifies that the base menubar has not been
//                modified, then enables the menu items and changes their names
//                where appropriate (eg. About PictureViewer ...).
//
//                Within this method, we request the clipboard focus.
//                If granted, the part can enable the appropriate Edit
//                menu items. Parts may retain the clipboard focus while
//                active, but must be prepared to relinquish it when
//                background parts want to inspect it.
//                Parts must also relinquish the clipboard focus in their
//                DisplayFrameRemoved/DisplayFrameClosed methods.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__AdjustMenus
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODFrame*                        frame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","AdjustMenus");

    ODBoolean    frameIsRoot = frame->IsRoot(ev);

    if ( frameIsRoot )
    {
        // The menubar object always calls the root part's AdjustMenus method before
        // calling the menu focus owner's. Because of this, we need to validate the
        // menubar in the case where we are the root part.
        // We are required to re-validate the menubar before displaying it because
        // any part could sway the base menubar at any time.
        if ( gGlobals->fMenuBar->IsValid(ev) == kODFalse )
            somSelf->InitializeMenuBar(ev);
    }

    if ( _fPicture )
    {
        gGlobals->fMenuBar->EnableCommand(ev, kODCommandCopy, kODTrue);
        gGlobals->fMenuBar->EnableCommand(ev, kCommandCrop, kODTrue);
        gGlobals->fMenuBar->EnableCommand(ev, kCommandScale, kODTrue);

        // Check the appropriate menu item according to the picture's display mode.
        if ( _fDisplayMode == kCommandCrop )
        {
            gGlobals->fMenuBar->CheckCommand(ev, kCommandCrop, kODTrue);
            gGlobals->fMenuBar->CheckCommand(ev, kCommandScale, kODFalse);
        }
        else
        {
            gGlobals->fMenuBar->CheckCommand(ev, kCommandCrop, kODFalse);
            gGlobals->fMenuBar->CheckCommand(ev, kCommandScale, kODTrue);
        }

        if ( !frameIsRoot )
        {
            // Enable the "View In Window" command if the frame is not the
            // root frame of the window and if a picture exists.
            gGlobals->fMenuBar->EnableCommand(ev, kODCommandViewAsWin, !frameIsRoot);
        }
    }
    else
    {
        gGlobals->fMenuBar->EnableCommand(ev, kODCommandCopy, kODFalse);
        gGlobals->fMenuBar->EnableCommand(ev, kCommandCrop, kODFalse);
        gGlobals->fMenuBar->EnableCommand(ev, kCommandScale, kODFalse);
    }

    TRY
        ODArbitrator* arbitrator = ODGetSession(ev, _fSelf)->GetArbitrator(ev);
        TempODFrame menuOwner = arbitrator->AcquireFocusOwner(ev, gGlobals->fMenuFocus);

        // There is no need to load a resource, create an ODIText object, set the menubar,
        // and cleanup, if we don't own the menu focus.
        if ( ODObjectsAreEqual(ev, frame, menuOwner) )
        {
            Str63 text;

            // Get the "about" string from our library's resources.
            // (note: ODGetIndString focuses the resource fork for us)
            ODGetIndString(text, kMenuStringResID, kAboutTextID);
            // Create an IText object to pass into the menubar.
            TempODIText    menuItem(CreateIText(gGlobals->fEditorScript, gGlobals->fEditorLanguage,
                                    (StringPtr)&text));
            // Change the "About" menu item text for our part.
            gGlobals->fMenuBar->SetItemString(ev, kODCommandAbout, menuItem);
        }
    CATCH_ALL
        // consume the exception, so don't set the ev parameter
    ENDTRY
}

//------------------------------------------------------------------------------
// Method:        HandleMenuEvent
// Origin:        PictureViewer
//
// Description:    This method is called by the part when a menu event is
//                received.
//
//                Using the menu bar object, we determine what the menu
//                command is, and call the appropriate method to handle it.
//------------------------------------------------------------------------------
SOM_Scope    ODBoolean
SOMLINK        PictureViewer__HandleMenuEvent
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODEventData*                    event,
                ODFrame*                        frame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","HandleMenuEvent");

    ODULong        menuResult    = event->message;
    ODUShort    menu        = HiWord(menuResult);
    ODUShort    item        = LoWord(menuResult);
    ODBoolean    result        = kODFalse;

    SOM_TRY
        switch( gGlobals->fMenuBar->GetCommand(ev, menu, item) )
        {
            case kODCommandAbout:
                somSelf->HandleDialogBox(ev, frame, kAboutBoxID, 0);
                result = kODTrue;
                break;

            case kODCommandCopy:
                somSelf->HandleCopy(ev, frame);
                result = kODTrue;
                break;

            case kODCommandViewAsWin:
                somSelf->Open(ev, frame);
                result = kODTrue;
                break;

            case kCommandCrop:
                somSelf->HandleDisplayMenuCommand(ev, kCommandCrop, frame);
                result = kODTrue;
                break;

            case kCommandScale:
                somSelf->HandleDisplayMenuCommand(ev, kCommandScale, frame);
                result = kODTrue;
                break;

            default:
                result = kODFalse;
                break;
        }

    SOM_CATCH_ALL
    SOM_ENDTRY

    return result;
}

//------------------------------------------------------------------------------
// Method:        HandleMouseEvent
// Origin:        PictureViewer
//
// Description:    This method is called by the part when a mouse event
//                is received.
//
//                A typical part would determine the event type (up/down)
//                and respond appropriately, but we have no "real"
//                content model, so we activate the part as appropriate
//                and call a generic method to handle the event.
//
// Remember:    When a frame is inactive, the first mouse up event
//                should activate it; inactive frames do not recieve
//                kODEvtMouseDown events.
//------------------------------------------------------------------------------
SOM_Scope    ODBoolean
SOMLINK        PictureViewer__HandleMouseEvent
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODEventData*                    event,
                ODFacet*                        facet,
                ODEventInfo*                    eventInfo
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","HandleMouseEvent");

    SOM_TRY

    // If the facet parameter is invalid, the mouse up occurred outside the
    // bounds of a Modal window, otherwise it should be treated normally.

    if ( facet != kODNULL )
    {
        if ( event->what == kODEvtMouseUp )
        {
            ODWindow* window = facet->GetWindow(ev);

            // Activate inactive windows on the first mouse up event.
            if ( !window->IsActive(ev) )
            {
                window->Select(ev);
            }
            else
            {
                // Activate the frame (if needed) on all subsequent
                // mouse up events.
                ODFrame* frame = facet->GetFrame(ev);

                // Get our state information from the PartInfo of the frame.
                CFrameInfo* frameInfo = (CFrameInfo*)frame->GetPartInfo(ev);

                // If this frame is not the active one, activate it by
                // requesting the appropriate foci.

                if ( !frameInfo->IsFrameActive() )
                {
                    if ( somSelf->ActivateFrame(ev, frame) )
                    {
                        // Keep track of which facet was the last active for
                        // positioning part windows.
                        frameInfo->SetActiveFacet(facet);
                    }
                    else
                    {
                        // We were unsuccessful in activating our frame.
                        return kODFalse;
                    }
                }
            }
        }
        else if ( event->what == kODEvtMouseDown )
        {
            // This is where the mouse down event is handled.
        }
    }
    else
    {
        // User clicked outside the bounds of a Modal window.
        SysBeep(1);
    }

    SOM_CATCH_ALL
    SOM_ENDTRY

    return kODTrue;
}

//------------------------------------------------------------------------------
// Method:        PartActivated
// Origin:        PictureViewer
//
// Description:    This method is called when the part has successfully acquired
//                the set of foci which allow it to run.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__PartActivated
              (
                 SampleCode_PictureViewer*        somSelf,
                 Environment*                    ev,
                 ODFrame*                        frame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","PartActivated");

    SOM_TRY
        // We are required to re-validate the menubar before displaying it
        // because any part can sway the base menubar at any time.
        if ( gGlobals->fMenuBar->IsValid(ev) == kODFalse )
            somSelf->InitializeMenuBar(ev);

        // Display our menu bar.
        gGlobals->fMenuBar->Display(ev);

        // And set our "active" state.
        CFrameInfo* frameInfo = (CFrameInfo*)frame->GetPartInfo(ev);
        frameInfo->SetFrameActive(kODTrue);
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        ActivateFrame
// Origin:        PictureViewer
//
// Description:    This method is called by the part when a kODEvtMouseUp
//                occurs in an inactive frame in an active window, and
//                when an OpenDoc document comes forward.
//
//                The part activates the frame by requesting the menu
//                focus and by calling FocusAcquired if we were successful.
//                The method returns true if no problems were encountered as
//                a signal to the caller that the frame is now active.
//------------------------------------------------------------------------------
SOM_Scope    ODBoolean
SOMLINK        PictureViewer__ActivateFrame
             (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODFrame*                        frame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","ActivateFrame");

    ODBoolean    activated = kODFalse;

    SOM_TRY
        // Request the set of foci necessary to become active.
        if ( ODGetSession(ev, _fSelf)->GetArbitrator(ev)
                    ->RequestFocusSet(ev, gGlobals->fUIFocusSet, frame) )
        {
            // Activate the part.
            somSelf->PartActivated(ev, frame);
            // We were able to become active.
            activated = kODTrue;
        }
    SOM_CATCH_ALL
    SOM_ENDTRY

    // Let our caller know we succeded or failed.
    return activated;
}

//------------------------------------------------------------------------------
// Method:        WindowActivating
// Origin:        PictureViewer
//
// Description:    This method is called by the part when a window activation
//                event (kODEvtActivate) occurs.
//
//                The part remembers the frame's active state and restores it when
//                events come in. If the frame is active and the window is being
//                sent into the background, remember to reactivate the part when
//                the window is reactivated.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__WindowActivating
             (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODFrame*                    frame,
                ODBoolean                    activating
            )
{
    SampleCode_PictureViewerMethodDebug("PictureViewer","WindowActivating");

    SOM_TRY

        CFrameInfo* frameInfo = (CFrameInfo*)frame->GetPartInfo(ev);

        // The window is being activated and we had the selection focus when
        // the window was deactivated, so activate ourself.
        if ( activating && frameInfo->FrameNeedsReactivating() )
        {
            // The window is being activated, so acquire our foci.
            if (somSelf->ActivateFrame(ev, frame))
                frameInfo->SetFrameReactivate(kODFalse);
        }
        else if ( !activating && frameInfo->IsFrameActive() )
        {
            // The window is being deactivated and we have the active part.
            // So give up our foci and remind ourselves that we need to request
            // the focus when the window is reactivated.

            frameInfo->SetFrameReactivate(kODTrue);
        }

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        AcquireFramesWindow
// Origin:        PictureViewer
//
// Description:    This method is called by the part when a frame that has been
//                previously opened is being opened again.
//                The method retrieves the existing window for the frame
//                and returns it.
//------------------------------------------------------------------------------
SOM_Scope    ODWindow*
SOMLINK        PictureViewer__AcquireFramesWindow
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODFrame*                     frame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","AcquireFramesWindow");

    ODWindow*    window = kODNULL;

    SOM_TRY
        CFrameInfo*    frameInfo = (CFrameInfo*)frame->GetPartInfo(ev);
        ODWindow* window = frameInfo->AcquirePartWindow(ev);
    SOM_CATCH_ALL
    SOM_ENDTRY

    return window;
}

//------------------------------------------------------------------------------
// Method:        CreateWindow
// Origin:        PictureViewer
//
// Description:    This method is called by the part when a window is
//                being opened on a frame.
//
//                The part determines the new window's name, position,
//                and size, and creates a Macintosh document window. The
//                part registers the window with OpenDoc to facilitate
//                the creation of a window object and the root frame for
//                the window.
//------------------------------------------------------------------------------
SOM_Scope    ODWindow*
SOMLINK        PictureViewer__CreateWindow
            (
                SampleCode_PictureViewer        *somSelf,
                Environment                        *ev,
                ODFrame*                        frame,
                ODType                            frameType,
                WindowProperties*                windowProperties
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","CreateWindow");

    ODPlatformWindow    platformWindow    = kODNULL;
    ODWindow*            window            = kODNULL;

    ODVolatile(platformWindow);
    ODVolatile(window);

    SOM_TRY
        // Using the name and the calculated rectangle, create a new window.
        // Note that we are allocating the window record in temp mem using
        // the OpenDoc memory mgr. This helps reduce app heap usage.
        // In addition, OpenDoc requires that all new windows be initially
        // hidden so that it can correctly layer windows/palettes.
        platformWindow = NewCWindow((Ptr)ODNewPtr(sizeof(WindowRecord)),
                                    &(windowProperties->boundsRect),
                                    windowProperties->title,
                                    kODFalse,                 /* visible */
                                    windowProperties->procID,
                                    (WindowPtr)-1L,
                                    windowProperties->hasCloseBox,
                                    windowProperties->refCon);

        if ( platformWindow )
        {
            ODWindowState* windowState = _fSession->GetWindowState(ev);

            // Shoud the window be saved in the document? Yes if the root frame is
            // persistent.
            ODBoolean saveWindow = ODISOStrEqual(frameType, kODFrameObject);

            // Tell the window object that we will be disposing the window record
            // when the root frame is closed/removed.
            ODBoolean shouldDispose = kODFalse;

            // Determine whether we are creating a new window (frame is null),
            // or opening a previously saved window (frame is valid).

            if ( frame == kODNULL )
            {
                // Tell OpenDoc about it by creating an OpenDoc window object.
                window = windowState->
                            RegisterWindow(ev,
                                platformWindow,                    // Macintosh WindowPtr
                                frameType,                        // Frame type (Persistent/Non-persistent)
                                windowProperties->isRootWindow,    // Is this a document window?
                                windowProperties->isResizable,    // Is this window resizeable?
                                windowProperties->isFloating,    // Is this window floating?
                                saveWindow,                        // Should this window be persistent?
                                shouldDispose,                    // (see comment above)
                                _fSelf,                            // Part reference to us
                                gGlobals->fFrameView,            // What view should the window have?
                                gGlobals->fMainPresentation,    // What presentation should the window have?
                                windowProperties->sourceFrame);    // The display frame being opened, if any
            }
            else
            {
                // Tell OpenDoc about it by creating an OpenDoc window object.
                window = windowState->
                            RegisterWindowForFrame(ev,
                                platformWindow,                    // Macintosh WindowPtr
                                frame,                             // Frame type (Persistent/Non-persistent)
                                windowProperties->isRootWindow,    // Is this a document window?
                                windowProperties->isResizable,    // Is this window resizeable?
                                windowProperties->isFloating,    // Is this window floating?
                                saveWindow,                        // Should this window be persistent?
                                shouldDispose,                    // (see comment above)
                                windowProperties->sourceFrame);    // The display frame being opened, if any
            }
        }

    SOM_CATCH_ALL
        // Clean up windows.
        CloseWindow(platformWindow);
        ODDisposePtr(platformWindow);
        ODReleaseObject(ev, window);

        // Get the right error message for the problem.
        ODSShort errMsgNum = (!frame && windowProperties->sourceFrame)
                            ? kErrCantOpenPartWindow : kErrCantOpenDocWindow;

        // Alert the user of the problem.
        somSelf->HandleDialogBox(ev, frame, kErrorBoxID, errMsgNum);
        // Change the error code value so the DocShell doesn't
        // display an error dialog.
        SetErrorCode(kODErrAlreadyNotified);
    SOM_ENDTRY

    return window;
}

//------------------------------------------------------------------------------
// Method:        CalcPartWindowSize
// Origin:        PictureViewer
//
// Description:    This method is called by the part to determine what
//                size a new window shoud be.
//------------------------------------------------------------------------------
SOM_Scope    Rect
SOMLINK        PictureViewer__CalcPartWindowSize
             (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODFrame*                    /*sourceFrame*/
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","CalcPartWindowSize");

    const ODSShort kOnePageWidth = 600;

    Rect    windowRect;

    SOM_TRY

    // If a source frame is given, the part is being asked to open one of
    // its display frames into a part window. Otherwise, we are being opened
    // as the root frame of the current document and should size the window
    // accordingly.
    if ( _fPicture )
    {
        // Set up the window's size to be that of the picture being displayed.
        windowRect = (**((PicHandle)_fPicture)).picFrame;

        OffsetRect(&windowRect, -windowRect.left, -windowRect.top);

        // Add space for the scrollbars
        windowRect.bottom += kScrollBarSize;
        windowRect.right += kScrollBarSize;
    }
    else
    {
        // Otherwise, just open a large window.
        SetRect(&windowRect, 0, 0,
                  ODQDGlobals.screenBits.bounds.right - (3 * kODLargeIconSize),
                  ODQDGlobals.screenBits.bounds.bottom
                      - GetMBarHeight() - kMacWindowTitleBarHeight - kALittleNudge);

        if (windowRect.right - windowRect.left > kOnePageWidth)
            windowRect.right = windowRect.left + kOnePageWidth;
    }

    SOM_CATCH_ALL
    SOM_ENDTRY

    return windowRect;
}

//------------------------------------------------------------------------------
// Method:        CalcPartWindowPosition
// Origin:        PictureViewer
//
// Description:    This method is called by the part to determine where
//                to align the new window (top left corner of the screen
//                or tiled to a frame).
//------------------------------------------------------------------------------
SOM_Scope    Rect
SOMLINK        PictureViewer__CalcPartWindowPosition
             (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODFrame*                    frame,
                Rect*                        partWindowBounds
            )
{
    SampleCode_PictureViewerMethodDebug("PictureViewer","CalcPartWindowPosition");

    ODFacet*            activeFacet;
    ODShape*            frameShape;
    ODRect                bbox;
    Rect                bounds;

    SOM_TRY

    // We need to know which facet of the frame we are opening to position
    // the part window.
    activeFacet = somSelf->GetActiveFacetForFrame(ev, frame);

    // This should never occur, but if it did, it would be fatal.
    // So we will just pass back the same rectangle.
    if ( activeFacet == kODNULL )
        return *partWindowBounds;

    // For the purposes of tiling, we need the to know the area of the
    // document the frame occupies. We do this by getting the bouding
    // box and offsetting it by the aggregate external window transform
    // of the facet.

    frameShape = activeFacet->GetFrame(ev)->AcquireFrameShape(ev, kODNULL);
    TempODTransform windowFrameTransform = activeFacet->AcquireWindowFrameTransform(ev, kODNULL);
    TempODShape boundsShape = ODCopyAndRelease(ev, frameShape);

    // Translate the bounds rect into window coordinates.
    boundsShape->Transform(ev, windowFrameTransform);

    // Get and convert the bounding box into a QuickDraw rectangle.
    boundsShape->GetBoundingBox(ev, &bbox);
    FixedToIntRect(bbox, bounds);

    // We then call our method to tile the part window.
    *partWindowBounds = TilePartWindow(ev, &bounds, partWindowBounds);

    // Set the port and origin so we can convert the rect to
    // global Window Mgr coordinates.
    SetPort(activeFacet->GetCanvas(ev)->GetQDPort(ev));
    SetOrigin(0,-kMacWindowTitleBarHeight);

    // Convert the local coordinates to global Window Mgr coordinates.
    LocalToGlobal((Point*)&partWindowBounds->top);
    LocalToGlobal((Point*)&partWindowBounds->bottom);

    SOM_CATCH_ALL
    SOM_ENDTRY

    return *partWindowBounds;
}

//------------------------------------------------------------------------------
// Method:            HandleCopy
// Origin:            PictureViewer
//
//    Description:    This method is called in response to the user
//                    selecting the Copy command. A promise is written
//                    out to the clipboard's storage unit, and is
//                    fulfilled later upon request.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__HandleCopy
            (
                  SampleCode_PictureViewer*        somSelf,
                  Environment*                    ev,
                  ODFrame*                        frame
             )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","HandleCopy");

    ODClipboard*    clipboard     = _fSession->GetClipboard(ev);

    // Remove any existing data on the clipboard.
    clipboard->Clear(ev);

    ODStorageUnit*    clipboardSU = clipboard->GetContentStorageUnit(ev);
    ODDraft*        srcDraft     = ODGetDraft(ev, _fSelf);
    ODDraft*        destDraft     = ODGetDraft(ev, clipboardSU);
    ODDraftKey        key            = kODNULLKey;

    ODVolatile(clipboard);
    ODVolatile(srcDraft);
    ODVolatile(key);

    SOM_TRY
        // Any modifications to the clipboard should be within BeginClone/EndClone
        key = srcDraft->BeginClone(ev, destDraft, frame, kODCloneCopy);

        // Annotate the clipboard with the frame shape.
        TempODShape frameShape = frame->AcquireFrameShape(ev, kODNULL);
        clipboardSU->AddProperty(ev, kODPropSuggestedFrameShape);
        frameShape->WriteShape(ev, clipboardSU);

        ODByteArray    data;
        data._maximum = 0;
        data._length = 0;
        data._buffer = kODNULL;

        // Add the content property and promised value.
        clipboardSU->AddProperty(ev, kODPropContents);
        clipboardSU->SetPromiseValue(ev, gGlobals->fPictScrapKind, 0,  &data, _fSelf);

        // Complete the clone transaction
        srcDraft->EndClone(ev, key);

    SOM_CATCH_ALL
        if ( key != kODNULLKey )
            srcDraft->AbortClone(ev, key);
        clipboard->Clear(ev);
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        HandleDisplayMenuCommand
// Origin:        PictureViewer
//
// Description:    Checks the appropriate menuitem in our Display menu.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__HandleDisplayMenuCommand
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODSLong                            command,
                ODFrame*                        frame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","HandleDisplayMenuCommand");

    SOM_TRY

        if ( _fPicture )
        {
            if ( _fDisplayMode != command )
            {
                gGlobals->fMenuBar->CheckCommand(ev, command, kODTrue);
                gGlobals->fMenuBar->CheckCommand(ev, _fDisplayMode, kODFalse);
                _fDisplayMode = command;

                frame->Invalidate(ev, kODNULL, kODNULL);

                // Change the source frame of this frame, if one exists, to match
                // the new view setting.
                CFrameInfo* frameInfo = (CFrameInfo*)frame->GetPartInfo(ev);
                if ( frameInfo->HasSourceFrame() )
                {
                    ODFrame* sourceFrame = frameInfo->GetSourceFrame(ev);
                    sourceFrame->Invalidate(ev, kODNULL, kODNULL);
                }

                // Change the dependent frame, if one exists, to match
                // the new view setting.
                if ( frameInfo->HasDependentFrame() )
                {
                    ODFrame* displayFrame = frameInfo->GetDependentFrame(ev);
                    displayFrame->Invalidate(ev, kODNULL, kODNULL);
                }
            }
        }

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        HandleDialogBox
// Origin:        PictureViewer
//
// Description:    This method is called by the part when a dialog needs to be
//                displayed (eg. the About Box). If a valid error number is
//                passed in, an error dialog will be displayed.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__HandleDialogBox
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODFrame*                     frame,
                ODSShort                     dialogID,
                ODUShort                     errorNumber
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","HandleDialogBox");

    ODFrame* focusFrame = frame;

    SOM_TRY

    // If the calling method does not have a frame available to it, we need to
    // locate a frame to use for requesting the modal focus. Find the first valid
    // frame in our display frames list.
    if ( focusFrame == kODNULL )
    {
        CListIterator fiter(_fDisplayFrames);
        for ( CFrameProxy* proxy = (CFrameProxy*)fiter.First();
                fiter.IsNotComplete(); proxy = (CFrameProxy*)fiter.Next() )
        {
            if ( proxy->FrameIsLoaded(ev) )
                focusFrame = proxy->GetFrame(ev);
            if ( focusFrame )
                break;
        }
    }

    // Our dialog boxes are modal so we must request the Modal focus to prevent
    // multiple modal dialogs being displayed simultaneously.

    if ( _fSession->GetArbitrator(ev)->RequestFocus(ev, gGlobals->fModalFocus, focusFrame) )
    {
        DialogPtr    dialog;
        ODSShort    itemHit;

        // Dim the frontmost document window.
        _fSession->GetWindowState(ev)->DeactivateFrontWindows(ev);

        ODSLong savedRef = BeginUsingLibraryResources();
        {
            dialog = GetNewDialog(kAboutBoxID, kODNULL, (WindowPtr) -1L);

            if ( dialog )
            {
                if ( errorNumber > 0 )
                {
                    Handle    itemHandle;
                    Rect    itemRect;
                    short    itemType;
                    Str255    errStr;

                    GetIndString(errStr, kErrorStringResID, errorNumber);
                    GetDialogItem(dialog, kErrStrFieldID, &itemType, &itemHandle, &itemRect);
                    SetDialogItemText(itemHandle, errStr);

                    // We don't need the cancel button for an error dialog.
                    HideDialogItem(dialog, cancel);

                    SetDialogDefaultItem(dialog, ok);
                }

                SetCursor(&ODQDGlobals.arrow);
                ShowWindow(dialog);
                ModalDialog(kODNULL, &itemHit);
                DisposeDialog(dialog);
            }
            else
            {
                // Could not load dialog...something is amiss.
                SysBeep(2);
            }
        }
        EndUsingLibraryResources(savedRef);

        // Inform the Arbitrator that we no longer require the Modal focus.
        _fSession->GetArbitrator(ev)->RelinquishFocus(ev, gGlobals->fModalFocus, focusFrame);

        // Highlight the frontmost document window.
        _fSession->GetWindowState(ev)->ActivateFrontWindows(ev);
    }
    else
    {
        // If we can't get the modal focus, then another modal dialog is
        // already being displayed.

        SysBeep(2);
    }

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        ReadPictureFile
// Origin:        PictureViewer
//
// Description:    Retrieve the PICT data from an OS file. The data
//                fork is examined first, and if no PICT data is present,
//                then search the resource fork.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__ReadPictureFile
               (
                 SampleCode_PictureViewer*        somSelf,
                 Environment*                    ev,
                  ODFacet*                        facet,
                  HFSFlavor*                        hfsInfo,
                  ODULong                            pictSize
              )
{
     SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","ReadPictureFile");

    // We're called when a PICT file is being internalized or dropped.

    ODBoolean    validPicture = kODFalse;
    ODHandle     tempPict = kODNULL;
    FSSpec         fileSpec;
    ODSShort    refNum;

    ODVolatile(tempPict);

    SOM_TRY
        // First check the data fork for the PICT data
        fileSpec = hfsInfo->fileSpec;

        // Open the data fork, and catch any errors.
        THROW_IF_ERROR( FSpOpenDF(&fileSpec, fsRdPerm, &refNum) );

        // Account for the 512-byte file header in 'PICT' file.
        ODSLong fileheader = 512;

        TRY
            THROW_IF_ERROR( GetEOF(refNum, (ODSLong*)&pictSize) );
            THROW_IF_ERROR( SetFPos(refNum, fsFromStart, fileheader) );
            pictSize -= fileheader;

            if ( pictSize > 0 )
            {
                tempPict = ODNewHandle(pictSize);

                TRY
                    TempODHandleLock hLock(tempPict);
                    THROW_IF_ERROR( FSRead(refNum, (ODSLong*)&pictSize, *hLock) );
                CATCH_ALL
                    ODDisposeHandle(tempPict);
                    RERAISE;
                ENDTRY

                if ( _fPicture != kODNULL )
                    ODDisposeHandle(_fPicture);

                _fPicture = tempPict;
                validPicture = kODTrue;
        }

        THROW_IF_ERROR( FSClose(refNum) );
        CATCH_ALL
            FSClose(refNum);
            RERAISE;
        ENDTRY

        if ( validPicture == kODFalse )
        {
            // Data wasn't present in the data fork, so check
            // the resource fork.
            refNum = FSpOpenResFile(&fileSpec, fsRdPerm);

            if ( refNum == -1 )
                THROW(ResError());

            TRY
                // We use our utility function Read1IndResource to read
                // the resource into memory.  We use this rather than just
                // calling Get1IndResource because Get1IndResource would
                // put the resoure in the application heap, and we don't
                // have much room available in the application heap. It also
                // detaches the resource from the resource fork it came from.
                tempPict = Read1IndResource(kPictureDataType, 1);
                if ( tempPict != kODNULL )
                {
                    // If successful, dispose of the existing data and
                    // replace it with the new.
                    if ( _fPicture != kODNULL )
                        ODDisposeHandle(_fPicture);

                    _fPicture = tempPict;
                    validPicture = kODTrue;
                }
                else
                {
                    // An error must have occurred when getting the PICT resource.
                    // Don't want to throw. Just internalize as nothing.
                }

            CATCH_ALL
                if ( tempPict != kODNULL )
                    ODDisposeHandle(tempPict);
                CloseResFile(refNum);
                RERAISE;
            ENDTRY

            // Close the resource fork.
            CloseResFile(refNum);
        }

    SOM_CATCH_ALL
        // Check the validity flag. If false, clear the
        // ev parameter so we can continue and just
        // display an empty picture (nothing).
        if ( !validPicture )
        {
            // Make sure our data handle doesn't contain any data.
            ODDisposeHandle(_fPicture);
            _fPicture = kODNULL;
        }
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        SetDirty
// Origin:        PictureViewer
//
// Description:    This method is called by the part when the content or
//                state of the part has been modified by the user and
//                the "Save As" menu item should be enabled.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__SetDirty
             (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","SetDirty");

    SOM_TRY
        // There is no need to repeatedly tell the draft we have changed;
        // once is sufficient.
        if ( !_fDirty && !_fReadOnlyStorage )
        {
            ODGetDraft(ev, _fSelf)->SetChangedFromPrev(ev);
            _fDirty = kODTrue;
        }
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        GenerateThumbnail
// Origin:        PictureViewer
//
// Description:    Creates a 64x64 pixel thumbnail of the picture in an
//                offscreen GWorld pixel map.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__GenerateThumbnail
             (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODFrame*                        frame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","GenerateThumbnail");

    SOM_TRY
        // As this is a Viewer, we know the content can't change. Thus, it
        // is sufficient to create the thumbnail representation once.
        if ( _fGWorld == kODNULL )
        {
            GDHandle    saveGDevice;
            CGrafPtr    savePort;
            Rect        bounds;

            // Call our utility routine to create the offscreen GWorld.
            _fGWorld = BeginGWorldThumbnail(&savePort, &saveGDevice);

            // Ideally, we want to preserve the picture's aspect ratios.
            // We are not doing that at this time.

            if ( _fGWorld != kODNULL )
            {
                SetRect(&bounds, 0, 0, kODThumbnailSize, kODThumbnailSize);

                // Draw the picture to the offscreen pixel image
                LockPixels( GetGWorldPixMap((GWorldPtr)_fGWorld) );
                DrawPicture((PicHandle)_fPicture, &bounds);
                UnlockPixels( GetGWorldPixMap((GWorldPtr)_fGWorld) );

                // Done creating our offscreen picture.
                EndGWorldThumbnail(savePort, saveGDevice);
            }
            else
                // We were unable to create out gWorld.
                THROW_IF_ERROR(kODErrOutOfMemory);
        }
    SOM_CATCH_ALL
        // If an error occurred, fall back to our default view type.
        frame->ChangeViewType(ev, gGlobals->fFrameView);
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        GetActiveFacetForFrame
// Origin:        PictureViewer
//
// Description:    This method is called by the part when it needs to know what
//                the current active facet is.
//
//                The part uses this method specifically to find the
//                facet of a source frame when opening a part window.
//------------------------------------------------------------------------------
SOM_Scope    ODFacet*
SOMLINK        PictureViewer__GetActiveFacetForFrame
             (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","GetActiveFacetForFrame");

    ODFacet*        facet = kODNULL;
    CFrameInfo*        frameInfo;

    ODVolatile(facet);

    SOM_TRY
        frameInfo = (CFrameInfo*)frame->GetPartInfo(ev);

        // If the frame is active, and it should be, get the active facet
        // from the frame state info.
        if ( frameInfo->IsFrameActive() )
        {
            facet = frameInfo->GetActiveFacet();
        }
        else
        {
            // Otherwise, iterate over the display frames looking for one
            // that has an active facet... there should be at least one.

            TempODFrameFacetIterator fiter(ev, frame);
            for ( ODFacet* selectedFacet = fiter.First();
                         fiter.IsNotComplete();
                         selectedFacet = fiter.Next() )
            {
                if ( selectedFacet->IsSelected(ev) )
                {
                    facet = selectedFacet;
                    break;        // found it; stop iteration
                }
            }
        }

        // If there are no active facets anywhere, this method should never
        // have been called, so signal an error.
        if ( facet == kODNULL )
            THROW(kODErrInvalidFrame);
    SOM_CATCH_ALL
    SOM_ENDTRY

    return facet;
}

//------------------------------------------------------------------------------
// Method:        GeometryChanged
// Origin:        ODPart
//
// Description:    This method is called when the ExternalTransform or
//                ClipShape of a facet on one of this part's display
//                frames changes.
//------------------------------------------------------------------------------
SOM_Scope void
SOMLINK PictureViewer__GeometryChanged
        (
            SampleCode_PictureViewer*        somSelf, Environment *ev,
            ODFacet*                         facet,
            ODBoolean                        clipShapeChanged,
            ODBoolean                        externalTransformChanged
        )
{
    SampleCode_PictureViewerMethodDebug("PictureViewer","GeometryChanged");

    SOM_TRY
        if ( clipShapeChanged )
            // Specifying kODNULL means to invalidate the clipShape (which was
            // calculated from the usedShape).
            facet->Invalidate(ev, kODNULL, kODNULL);
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        FulfillPromise
// Origin:        ODPart
//
// Description:    Fulfill a previously made promise by providing the actual data
//                the promise represents. The promiseSUView is a view into the same
//                storage unit value created by SetPromiseValue. The information about
//                the promise is encoded in the promiseSUView in the part handler's own
//                internal format. The promise data is written into the promiseSUView,
//                replacing the data stored in the part handler's format. When the promise
//                was made, a record of it was kept by this part. The promiseSUView contains
//                the part's information for that promise. The part uses the data in the
//                promiseSUView to determine which data to move/copy. The part then writes
//                the data into the promiseSUView.
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__FulfillPromise
            (
                SampleCode_PictureViewer*        somSelf,
                Environment*                    ev,
                ODStorageUnitView*                promiseSUView
            )
{
    SampleCode_PictureViewerData *somThis = SampleCode_PictureViewerGetData(somSelf);
    SampleCode_PictureViewerMethodDebug("PictureViewer","FulfillPromise");

    SOM_TRY
        // We are being asked to provide the data we promised in a previous
        // clipboard operation. We need to write out the actual data into the
        // value that we promised before.
        ODValue picturePtr = ODLockHandle(_fPicture);
        StorageUnitViewSetValue(promiseSUView, ev, ODGetHandleSize(_fPicture), picturePtr);
        ODUnlockHandle(_fPicture);
    SOM_CATCH_ALL
        ODUnlockHandle(_fPicture);
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        GetPrintResolution
// Origin:        ODPart
//
// Description:    Return the minimum print resolution, represented in dots per
//                inch, required to print the content of the specified
//                display frame.
//------------------------------------------------------------------------------
SOM_Scope    ODULong
SOMLINK        PictureViewer__GetPrintResolution
            (
                SampleCode_PictureViewer*    somSelf,
                Environment*                ev,
                ODFrame*                     /*frame*/
            )
{
    SampleCode_PictureViewerMethodDebug("PictureViewer","GetPrintResolution");

    return kMinImagingResolution;
}


//=======================================================================
//
// Unimplemented Methods • Unimplemented Methods • Unimplemented Methods
//
//=======================================================================

//------------------------------------------------------------------------------
// Method:        AcquireExtension
// Origin:        ODObject
//------------------------------------------------------------------------------
SOM_Scope    ODExtension*
SOMLINK     PictureViewer__AcquireExtension(SampleCode_PictureViewer *somSelf,
                                            Environment *ev, ODType extensionName)
{
    SampleCode_PictureViewerMethodDebug("PictureViewer","AcquireExtension");

    ODExtension* result;

    SOM_TRY
        // We don't support any extensions, but one of our parent classes might;
        result = SampleCode_PictureViewer_parent_ODPart_AcquireExtension(somSelf,ev,extensionName);
    SOM_CATCH_ALL
        result = kODNULL;
    SOM_ENDTRY

    return result;
}

//------------------------------------------------------------------------------
// Method:        HasExtension
// Origin:        ODObject
//------------------------------------------------------------------------------
SOM_Scope ODBoolean
SOMLINK     PictureViewer__HasExtension(SampleCode_PictureViewer *somSelf,
                                        Environment *ev, ODType extensionName)
{
    SampleCode_PictureViewerMethodDebug("PictureViewer","HasExtension");

    ODBoolean result;

    SOM_TRY
        // We don't support any extensions, but one of our parent classes might;
        result = SampleCode_PictureViewer_parent_ODPart_HasExtension(somSelf,ev,extensionName);
    SOM_CATCH_ALL
        result = kODFalse;
    SOM_ENDTRY

    return result;
}

//------------------------------------------------------------------------------
// Method:        ReleaseExtension
// Origin:        ODObject
//------------------------------------------------------------------------------
SOM_Scope void
SOMLINK PictureViewer__ReleaseExtension(SampleCode_PictureViewer *somSelf,
                                        Environment *ev, ODExtension* extension)
{
    SampleCode_PictureViewerMethodDebug("PictureViewer","ReleaseExtension");

    SOM_TRY
        // We don't support any extensions, but one of our parent classes might;
        SampleCode_PictureViewer_parent_ODPart_ReleaseExtension(somSelf,ev,extension);
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        HighlightChanged
// Origin:        ODPart
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__HighlightChanged(SampleCode_PictureViewer*    somSelf,
                                            Environment* ev, ODFacet* /*facet*/)
{
    SampleCode_PictureViewerMethodDebug("PictureViewer","HighlightChanged");
}



//------------------------------------------------------------------------------
// Method:        ContainingPartPropertiesUpdated
// Origin:        ODPart
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__ContainingPartPropertiesUpdated(SampleCode_PictureViewer *somSelf,
                                    Environment *ev, ODFrame* /*frame*/, ODStorageUnit* /*propertyUnit*/)
{
    SampleCode_PictureViewerMethodDebug("PictureViewer","ContainingPartPropertiesUpdated");
}

//------------------------------------------------------------------------------
// Method:        PresentationChanged
// Origin:        ODPart
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__PresentationChanged(SampleCode_PictureViewer *somSelf,
                                                Environment *ev, ODFrame* /*frame*/)
{
    SampleCode_PictureViewerMethodDebug("PictureViewer","PresentationChanged");
}

//------------------------------------------------------------------------------
// Method:        SequenceChanged
// Origin:        ODPart
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__SequenceChanged(SampleCode_PictureViewer *somSelf,
                                        Environment *ev, ODFrame* /*frame*/)
{
    SampleCode_PictureViewerMethodDebug("PictureViewer","SequenceChanged");
}

//------------------------------------------------------------------------------
// Method:        CanvasChanged
// Origin:        ODPart
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__CanvasChanged(SampleCode_PictureViewer* somSelf,
                                            Environment* ev, ODFacet* /*facet*/)
{
    SampleCode_PictureViewerMethodDebug("PictureViewer","CanvasChanged");
}

//------------------------------------------------------------------------------
// Method:        CanvasUpdated
// Origin:        ODPart
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__CanvasUpdated(SampleCode_PictureViewer *somSelf, Environment *ev,
                                ODCanvas* /*canvas*/)
{
    SampleCode_PictureViewerMethodDebug("PictureViewer","CanvasUpdated");
}

//------------------------------------------------------------------------------
// Method:        LinkStatusChanged
// Origin:        ODPart
//------------------------------------------------------------------------------
SOM_Scope    void
SOMLINK        PictureViewer__LinkStatusChanged(SampleCode_PictureViewer *somSelf,
                                            Environment *ev, ODFrame* /*frame*/)
{
    SampleCode_PictureViewerMethodDebug("PictureViewer","LinkStatusChanged");
}